diff --git a/PIPELINE.md b/PIPELINE.md
new file mode 100644
index 0000000..d64145b
--- /dev/null
+++ b/PIPELINE.md
@@ -0,0 +1,47 @@
+# How this homepage ships itself
+
+This repo is fully automated: from an idea written as an issue to the live site at
+**https://homepage.ffaerber.duckdns.org** — no human in the routine path.
+
+## The pipeline
+
+```
+issue (autopilot label)                     ffaerber/homepage
+  └─> @pm plans, delegates a dev
+        └─> @senior/@junior build on ai/issue-N, PR opens automatically
+              └─> @qa reviews the diff + renders the site headless
+                    ├─ BOUNCE -> dev fixes (max 3 rounds)
+                    └─ APPROVE -> @pm merges (autopilot only)
+                          └─> build-and-push (.gitea/workflows/build.yml)
+                                ├─ docker build -> git.ffaerber.duckdns.org/ffaerber/homepage:latest
+                                └─ dispatches homelab's deploy workflow (TOKEN_DEPLOY)
+                                      └─> ffaerber/homelab deploy.yml       (swarm)
+                                            ├─ docker stack deploy (re-resolves :latest)
+                                            ├─ verify: replicas converge + HTTP smoke
+                                            └─ on failure: opens a triage issue, pings @pm
+```
+
+## The pieces
+
+| Piece | Where | What it does |
+|---|---|---|
+| Agent team | `.gitea/workflows/ai-agent.yml` → `gitea/agents` (reusable) | Issues/comments trigger @pm/@senior/@junior/@qa; `autopilot` label lets @pm merge approved PRs itself. |
+| Site | `index.html` + `styles.css` | Static, no framework. Dark-mode + mobile friendly. |
+| Image | `Dockerfile` | nginx:alpine serving the two files, with a healthcheck. |
+| Build + push | `.gitea/workflows/build.yml` | On every push to `main`: build, tag `:latest` + `:sha`, push to this Gitea's registry (public — pullable without creds). |
+| Deploy hand-off | last step of `build.yml` | `POST /repos/ffaerber/homelab/actions/workflows/deploy.yml/dispatches` with `TOKEN_DEPLOY` (the `deploy` bot, write on homelab only). Deterministic — no agent involved. |
+| Serving | `ffaerber/homelab` `docker-compose.yml` (`homepage` service) | Swarm service behind Traefik: `homepage.ffaerber.duckdns.org`, TLS via Let's Encrypt. |
+| Failure path | homelab `deploy.yml` verify job | If replicas don't converge or the URL stops answering, a triage issue is opened and @pm is mentioned to drive a fix. |
+
+## How to change the site
+
+1. Open an issue describing the change (content is provided in the issue body — the agents don't invent copy).
+2. Add the `autopilot` label if it should ship without a human merge.
+3. Wait a few minutes; the change is live. Failures come back as issues, not silence.
+
+A direct push to `main` works too and triggers the same build → deploy chain.
+
+## History
+
+- **#5** — first real page: 17 project cards from GitHub READMEs, four sections.
+- **#7** — redesign into a personal showcase: first-person stories per project, section intros, tech tags de-emphasized. Shipped end-to-end by the agent team with one QA bounce round and zero human intervention.