diff --git a/README.md b/README.md
index 8334465..41c12c5 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,27 @@ What the runtime provides underneath:
   decisions (send the newsletter, onboard an invited applicant, commit
   an approved development proposal).
 
+## This repo runs the instance
+
+Besides the content, this repo owns the uhhm.no portal instance
+itself. `.gitea/workflows/deploy.yml` pins the portal version:
+
+```yaml
+env:
+  PORTAL_RELEASE: v0.1.0   # a release tag on uhhm/portal
+```
+
+Upgrading (or downgrading) portal is bumping that line and pushing —
+the workflow downloads the pinned release artifact, ships it, rewrites
+the instance env from this repo's Actions variables/secrets, restarts
+`app@uhhm-portal`, and refreshes the Caddy route. Nothing else
+deploys this site; a push to the portal repo only publishes a new
+version for repos like this one to opt into.
+
+Day to day you rarely touch it: content edits (any `*.yaml` here)
+hot-reload without a deploy, and the deploy workflow only triggers on
+changes to itself (or a manual run from the Actions tab).
+
 ## The optimal usecase, in order
 
 A full concern — say, tracking a new kind of actor — is stood up