diff --git a/README.md b/README.md
index b4fbbb4..ecef74e 100644
--- a/README.md
+++ b/README.md
@@ -110,3 +110,4 @@ its own doc per provider:
 
 * [Buildkite](docs/buildkite.md)
 * [Tekton](docs/tekton.md)
+* [sourcehut](docs/sourcehut.md)
diff --git a/docs/sourcehut.md b/docs/sourcehut.md
new file mode 100644
index 0000000..75e8d52
--- /dev/null
+++ b/docs/sourcehut.md
@@ -0,0 +1,88 @@
+# sourcehut
+
+The sourcehut provider submits jobs to a
+[builds.sr.ht](https://man.sr.ht/builds.sr.ht/) instance. Each Tangled
+workflow becomes one job: tack submits the job via GraphQL, polls it
+until terminal, and publishes `sh.tangled.pipeline.status` records on
+each transition.
+
+## Configure tack
+
+| Env var                 | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| `TACK_SOURCEHUT_TOKEN`  | Personal access token for builds.sr.ht (enables provider) |
+| `TACK_SOURCEHUT_INSTANCE` | Base URL override (default `https://builds.sr.ht`)   |
+
+Generate a token at `https://meta.sr.ht/oauth2/personal-token` with
+`builds.sr.ht/JOBS:RW` access, set the `TACK_SOURCEHUT_TOKEN=$token` env var,
+then start tack.
+
+## Workflow YAML
+
+Your sourcehut build manifest is defined via tangled workflow inline - see `tack.sourcehut.manifest`.
+It is submitted to builds.sr.ht verbatim, with a few `TACK_*` environment
+variables merged into its top-level `environment:` map.
+
+```yaml
+when:
+  - event: ["push"]
+    branch: ["main"]
+
+engine: tack
+
+tack:
+  sourcehut:
+    manifest: |
+      image: alpine/edge
+      sources:
+        - https://tangled.org/j3s.sh/testy
+      tasks:
+        - test: |
+            ls -l testy
+```
+
+Optional fields:
+
+```yaml
+tack:
+  sourcehut:
+    instance: https://selfhosted.sr.ht.example.org
+    tags: ["tack", "ci"]
+    note: "manual note for the job list"
+    secrets: true
+```
+
+* `instance`: full URL (with scheme) of an alternate builds.sr.ht
+  deployment. Defaults to the provider's configured instance.
+* `tags`: passed through to the submit API. Defaults to `["tack"]` so
+  jobs are filterable in the builds.sr.ht UI.
+* `note`: passed through to the submit API. Defaults to
+  `tangled: <workflow> @ <short-commit>`.
+* `secrets`: opt in to sourcehut secret injection. Default `false`.
+
+## Injected environment
+
+Tack merges the following into the manifest's `environment:` map
+before submitting. These can be overridden via user definition.
+
+| Variable             | Value                                  |
+| -------------------- | -------------------------------------- |
+| `TACK_KNOT`          | Knot host the trigger came from        |
+| `TACK_PIPELINE_RKEY` | Pipeline record rkey                   |
+| `TACK_WORKFLOW`      | Workflow name                          |
+| `TACK_WORKFLOW_RAW`  | Raw workflow YAML body                 |
+| `TACK_ACTOR`         | Triggering DID                         |
+| `TACK_COMMIT`        | Commit SHA                             |
+| `TACK_BRANCH`        | Branch ref                             |
+
+## Status mapping
+
+| builds.sr.ht status   | tack status |
+| --------------------- | ----------- |
+| `pending`, `queued`   | `pending`   |
+| `running`             | `running`   |
+| `success`             | `success`   |
+| `failed`, `timeout`   | `failed`    |
+| `cancelled`           | `cancelled` |
+
+Unknown upstream statuses are logged.