Workshop facilitation
This page is for whoever is running the room, not for participants. It holds the agenda, the timings, what to do when a block overruns, and the table connecting every slide to the page it links to.
That table is not maintained by hand. The build checks all 34 routes, all 27 slide links, and every heading they point at — so a slide can never link to a heading that has been renamed away.
Before anyone arrives: run the Start here preflight yourself, confirm the starter installs and the documentation build is green, and set up a clean directory per participant for their test output. Check PostgreSQL is up before anyone opens a browser.
Have the prepared path ready even if you plan to run the optional live block. A live failure is on the schedule, not a surprise — it costs five minutes and changes nothing else about the day.
The workshop runs over three days: Monday from the afternoon, then Tuesday and Wednesday in full.
The two headings below still say “Day 1” and “Day 2”, and the recovery sections after them still say D1 and D2. Those names are wired into the slide deck and cannot be renamed before the workshop. Read “Day 1” as Monday plus Tuesday, and “Day 2” as Wednesday.
Monday afternoon and Tuesday. Monday installs and reads; Tuesday builds.
| Day | Time | Block | What everyone should have afterwards |
|---|---|---|---|
| Mon | 13:30–14:15 | Welcome, what the three days cover | every machine through the preflight |
| Mon | 14:15–15:30 | Install the release, check the versions | the same versions resolved on every machine |
| Mon | 15:30–15:45 | Break | — |
| Mon | 15:45–17:00 | Read the project | everyone can point at the workflow and its wait |
| Tue | 09:00–12:15 | Build the vacation approval, run it | one completed run and its instance ID |
| Tue | 13:15–15:15 | Test it, then read state and events | passing test output and the event list |
| Tue | 15:30–17:00 | Coverage, restart, checkpoint | the before and after of the coverage change |
Tuesday morning has no break in the table. Take one anyway, around 10:30 — the table only lists the breaks the slide deck links to, not every break there is.
The participant-facing checkpoints are on Day 1: Vacation approval.
Wednesday.
| Time | Block | What everyone should have afterwards |
|---|---|---|
| 09:00–10:45 | Baseline, read multi-role, change one stage | one change they can explain from the events |
| 11:00–12:40 | Identity: hooks, origin routing, visibility | the wrong person visibly refused |
| 13:40–15:00 | Assignee sources and authorization | membership decided at the moment of acting |
| 15:15–17:00 | CI, second local target, optional live block | CI output and the second target’s result |
Use Day 2: Multi-role approval then CI and deployment, in that order.
If install or preflight fails, save the output first. Then check, in order: package access, PostgreSQL, the starter revision.
Only move on once Install and verify the release is genuinely working. Carrying a broken install into the next block costs you the afternoon.
By lunch everyone should have a working starter and one recorded run.
Don’t start the test block with anyone still stuck on packages or identity — they will not catch up, and you’ll be debugging two problems at once after lunch.
If the coverage change gives someone a different result, keep both the before and after source versions — the difference is usually visible immediately. Re-run the visibility assertion, then continue to Restart and resume.
Restore the Day 2 baseline before looking at anyone’s change.
When a stage edit goes wrong, the way back is the known starter revision and the passing test — never editing the event stream. If someone reaches for that, stop them; it’s the one habit that makes everything afterwards untrustworthy.
Announce the optional live block at lunch so nobody is surprised either way. Confirm the endpoint, the credentials, provider routing, and run the five-minute preflight.
If any of it fails, keep the group on the local path and note the live block as preview only. Say that out loud — participants should leave knowing which parts they saw actually run.
If CI or the second copy fails, compare the commit, the dependency set, the database image, the configuration, and the output. One of those five differs.
Don’t reach for a remote promotion step to get around it — there isn’t one. Return to Deploy and verify.
The deck links straight into the pages below. Both tables are generated from the same route data the build checks, so they cannot drift from what is published.
Status column: required means the page describes work still to be implemented,
current means it documents something that exists and is supported, and
preview means it is explicitly not part of what you can run today.
“Runs against” in the second table: fixture is prepared test data, live
needs a real provider, break is a break, and preview is a block that only
shows what is not available yet.
| Route | Group | Anchors | Status |
|---|---|---|---|
| / | front matter | — | required |
| /404 | front matter | — | current |
| /start-here/ | Start Here | preflight, install-and-verify-the-release, first-verified-run, recovery | required |
| /tutorial/ | Tutorial | — | required |
| /tutorial/vacation-approval/ | Tutorial | project-map, build-the-workflow, first-run, workflow-test, state-events-and-audit, vacation-coverage, restart-and-resume, day-1-checkpoint | required |
| /tutorial/multi-role-approval/ | Tutorial | day-2-baseline, read-the-workflow, ordered-stages-and-recipient-attributes | required |
| /tutorial/ci-and-deployment/ | Tutorial | ci-with-fixtures, project-release, deploy-and-verify | required |
| /identity-integration/ | Identity Integration | oidc-to-principal-route, provider-id-invariant, ownership | current |
| /identity-integration/hooks-and-origin-routing/ | Identity Integration | hook-discovery, origin-routing, principals-account | current |
| /identity-integration/fixtures-and-visibility/ | Identity Integration | principal-fixtures, step-visibility, stale-authority | required |
| /identity-integration/assignee-sources/ | Identity Integration | stable-principals-first, when-to-use-a-resolver, resolver-contract | current |
| /identity-integration/role-engine-adapter/ | Identity Integration | live-gate, adapter-swap, fixture-fallback | preview |
| /guides/concepts/ | Guides | — | current |
| /guides/authoring-workflows/ | Guides | define-workflow, validation, replay-rules, sub-workflows-and-parallel-steps | current |
| /guides/testing-workflows/ | Guides | — | current |
| /guides/bindings-and-connectors/ | Guides | — | current |
| /guides/errors-and-retries/ | Guides | — | current |
| /guides/authorization/ | Guides | functions-scopes-and-receipts, access-activation | required |
| /guides/audit-evidence/ | Guides | — | required |
| /guides/ci/ | Guides | — | required |
| /guides/deployment/ | Guides | — | required |
| /reference/ | Reference | — | required |
| /reference/workflow-api/ | Reference | — | current |
| /reference/hooks/ | Reference | — | current |
| /reference/testing/ | Reference | — | current |
| /reference/configuration/ | Reference | — | current |
| /reference/commands-and-verification/ | Reference | — | required |
| /reference/graphql/ | Reference | — | current |
| /troubleshooting/ | Troubleshooting | package-access, postgres-and-docker, proxy-and-tls, gatekeeper-and-signing, origin-and-provider-mismatch, workflow-test-failures, role-engine-unavailable | required |
| /preview/ | Preview | executable-vs-preview, parked-examples | preview |
| /preview/delegation-and-impersonation/ | Preview | — | preview |
| /preview/staging-and-production/ | Preview | — | preview |
| /preview/observability/ | Preview | — | preview |
| /workshop/ | Workshop | facilitator-preflight, agenda-day-1, agenda-day-2, d1-morning-recovery, d1-lunch-checkpoint, d1-afternoon-recovery, d2-morning-recovery, d2-lunch-and-live-gate, d2-afternoon-recovery, slide-map, facilitator-notes-de | required |
| ID | Time | Runs against | Target | Slide |
|---|---|---|---|---|
| d1-welcome | Mon 13:30 | fixture | /start-here/#preflight | Day 1 / 01 Workshop contract |
| d1-install | Mon 14:15 | fixture | /start-here/#install-and-verify-the-release | Day 1 / 02 Trust before execution |
| d1-break-am | Mon 15:30 | break | /workshop/#d1-morning-recovery | Day 1 / Morning break |
| d1-project | Mon 15:45 | fixture | /tutorial/vacation-approval/#project-map | Day 1 / 03 One deployable project |
| d1-build-vacation | Tue 09:00 | fixture | /tutorial/vacation-approval/#build-the-workflow | Day 1 / 04 A durable approval |
| d1-first-run | Tue 10:45 | fixture | /tutorial/vacation-approval/#first-run | Day 1 / 05 Start, wait, decide |
| d1-lunch | Tue 12:15 | break | /workshop/#d1-lunch-checkpoint | Day 1 / Lunch |
| d1-test | Tue 13:15 | fixture | /tutorial/vacation-approval/#workflow-test | Day 1 / 06 A test is a normal Vitest test |
| d1-audit | Tue 14:30 | fixture | /tutorial/vacation-approval/#state-events-and-audit | Day 1 / 07 Three kinds of evidence |
| d1-break-pm | Tue 15:15 | break | /workshop/#d1-afternoon-recovery | Day 1 / Afternoon break |
| d1-reassign | Tue 15:30 | fixture | /tutorial/vacation-approval/#vacation-coverage | Day 1 / 08 Coverage without hidden authority |
| d1-restart | Tue 16:15 | fixture | /tutorial/vacation-approval/#restart-and-resume | Day 1 / 09 Durable means restartable |
| d1-close | Tue 16:45 | fixture | /tutorial/vacation-approval/#day-1-checkpoint | Day 1 / 10 Evidence checkpoint |
| d2-recap | Wed 09:00 | fixture | /tutorial/multi-role-approval/#day-2-baseline | Day 2 / 01 Restore before changing |
| d2-read | Wed 09:20 | fixture | /tutorial/multi-role-approval/#read-the-workflow | Day 2 / 02 One case, ordered decisions |
| d2-stages | Wed 10:00 | fixture | /tutorial/multi-role-approval/#ordered-stages-and-recipient-attributes | Day 2 / 03 Selection before assignment |
| d2-break-am | Wed 10:45 | break | /workshop/#d2-morning-recovery | Day 2 / Morning break |
| d2-hooks | Wed 11:00 | fixture | /identity-integration/hooks-and-origin-routing/ | Day 2 / 04 Provider-scoped identity |
| d2-visibility | Wed 12:00 | fixture | /identity-integration/fixtures-and-visibility/ | Day 2 / 05 Eligibility is current membership |
| d2-lunch | Wed 12:40 | break | /workshop/#d2-lunch-and-live-gate | Day 2 / Lunch |
| d2-resolver | Wed 13:40 | fixture | /identity-integration/assignee-sources/ | Day 2 / 06 Resolve only when the provider must |
| d2-auth | Wed 14:20 | fixture | /guides/authorization/#functions-scopes-and-receipts | Day 2 / 07 Relationship-aware Fine-Grained Authorization |
| d2-break-pm | Wed 15:00 | break | /workshop/#d2-afternoon-recovery | Day 2 / Afternoon break |
| d2-ci | Wed 15:15 | fixture | /tutorial/ci-and-deployment/#ci-with-fixtures | Day 2 / 08 The same project in CI |
| d2-deploy | Wed 15:50 | fixture | /tutorial/ci-and-deployment/#deploy-and-verify | Day 2 / 09 Deployment is startup plus proof |
| d2-role-engine | Wed 16:10 | live | /identity-integration/role-engine-adapter/ | Day 2 / 10 Optional live adapter |
| d2-close | Wed 16:50 | preview | /preview/#executable-vs-preview | Day 2 / 11 Executable now, preview later |
- Start Here: /start-here/
- Tutorial: /tutorial/, /tutorial/vacation-approval/, /tutorial/multi-role-approval/, /tutorial/ci-and-deployment/
- Identity Integration: /identity-integration/, /identity-integration/hooks-and-origin-routing/, /identity-integration/fixtures-and-visibility/, /identity-integration/assignee-sources/, /identity-integration/role-engine-adapter/
- Guides: /guides/concepts/, /guides/authoring-workflows/, /guides/testing-workflows/, /guides/bindings-and-connectors/, /guides/errors-and-retries/, /guides/authorization/, /guides/audit-evidence/, /guides/ci/, /guides/deployment/
- Reference: /reference/, /reference/workflow-api/, /reference/hooks/, /reference/testing/, /reference/configuration/, /reference/commands-and-verification/, /reference/graphql/
- Troubleshooting: /troubleshooting/
- Preview: /preview/, /preview/delegation-and-impersonation/, /preview/staging-and-production/, /preview/observability/
- Workshop: /workshop/
Verbindlich sind die englischen Seiten. Das hier ist nur für dich, zum schnellen Nachlesen zwischen zwei Blöcken.
- Montag ab 13:30: Ankommen, installieren, das Projekt lesen — mehr nicht. Wer am Montag sauber installiert hat, verliert am Dienstag keine Stunde. Die Pause um 15:30 steht fest: dreieinhalb Stunden am Anreisetag ohne Pause funktionieren nicht, und genau in diesem Block hängen acht Installationen gleichzeitig.
- Dienstag: Der ganze Tag gehört dem Urlaubsantrag: von Hand bauen, testen, den Vertretungsfall durchspielen, neu starten. Der Neustart ist der Moment, in dem es klickt — nimm dir dafür Zeit und kürze lieber vorher. Die Vormittagspause gegen 10:30 findet statt, auch wenn sie nicht in der Tabelle steht; dort stehen nur die Pausen, die aus den Folien verlinkt sind.
- Mittwoch: Multi-Role-Approval lesen und ändern, dann Identität, Autorisierung, CI und das zweite lokale Ziel. Der Live-Block am späten Nachmittag ist optional und darf ausfallen.
- Womit alles läuft: Alles läuft auf vorbereiteten Testdaten, auf jedem Rechner gleich. Urlaubsantrag und Multi-Role-Approval sind die beiden Beispiele, die wirklich laufen; alles andere ist zum Lesen.
- Zeitführung: Jeden Block mit einem Satz eröffnen: was machen wir, und woran sehen wir, dass es geklappt hat. Wenn die Zeit reißt, den beschriebenen Wiedereinstieg nehmen und den nächsten Block pünktlich beginnen.
- Was sie mitnehmen sollen: Nach jedem Block getrennt sichern: Paketversionen, PostgreSQL-Ziel, Zustand des Laufs, die Liste der Ereignisse, die geschwärzte Testausgabe. Getrennt, nicht als ein einzelner Screenshot — einzeln sind sie später nachvollziehbar.
- Wenn etwas bricht: Erst die Fehlerausgabe einfrieren, dann neu starten — nie umgekehrt. Danach zurück auf den letzten Stand, der nachweislich lief. Ereignisse werden nie geändert oder gelöscht; wer damit anfängt, kann dem Rest des Tages nicht mehr trauen.
- Der Vertretungsfall am Dienstag: Sieht aus wie eine formale Vertretung, ist aber keine. Dort ändert sich nur die Mitgliedschaft, und das Programm liest neu nach, wer gerade zuständig ist. Sag das laut, sonst nimmt es jemand als Zusage mit ins Haus.
- Live-Block am Mittwoch: Nur zeigen, wenn der Fünf-Minuten-Check vorher komplett durchläuft. Tut er das nicht: offen sagen, dass er nicht läuft, und auf den Testdaten weitermachen. Das kostet nichts und ändert an keiner Übung etwas.
- Was es noch nicht gibt: Autorisierung ist in 0.2.0 ausdrücklich Vorschau. Vertretung im formalen Sinn, Handeln unter fremder Identität, Staging, Produktion und die Anbindung an ein echtes Identitätssystem gibt es nicht. Nicht als „kommt bald“ verkaufen — die Leute planen danach.
Zum Schluss drei Sätze: Was ist heute wirklich gelaufen, was liegt schriftlich vor, und was war ausdrücklich nur Vorschau.