Training deck

The tutorials are written to be worked through one lesson at a time, each starting from a cold shell. That is the right shape for a learner and the wrong shape for a demo: fifteen lessons repeat the same environment preamble, re-derive the same identifiers, and ask you to complete fourteen browser sign-ins.

This deck is the same path — set-up through Run your first agent — replayed as one continuous session in front of an audience. Every command is lifted verbatim from the lesson it came from; what is removed is only the repetition that independent runnability forced.

It is presenter material, not a lesson. When you want to learn plexsphere, work the tutorials. When you want to show it, run this.

The chapters

#	Chapter	Source lesson
1	The cast	the seeded world every chapter acts in
2	Stack and sign-in	Set up your local plexsphere
3	Read a tenant	Explore your first Domain
4	Write into a tenant	Build in your first Domain
5	Access through groups	Grant access through a Group
6	Labels	Label your first Project
7	Machine identity	Give a machine its own identity
8	The provisioning catalog	Register a Blueprint, Create a Cloud, Issue a Cloud Credential
9	Two-party governance	Assign a Cloud Credential
10	Provision a Resource	Provision a cloud Resource
11	Access without keys	Reach your Resource
12	Watch it	Watch your Domain
13	The mesh by hand	Enrol your first Node
14	The real agent	Run your first agent
15	Logs leave the platform	Route logs to your own collector

Chapters 3 to 7 are the tenancy story and stand alone. Chapters 8 to 12 are one connected provisioning arc — do not start it in the middle. Chapters 13 to 15 are the mesh arc and need only chapter 2, so they are the safest chapters to demo on their own.

Render it as slides

make demo-deck

The target renders every chapter into a self-contained deck under bin/demo/ and prints the file URL to open. The bundle inlines its own markdown, so it opens straight off the filesystem — no local server, and it still works on a machine with no toolchain on it.

Arrow keys or space step through the slides, Esc shows the overview grid, and S opens reveal's speaker view with a timer and the next-slide preview. Slides are split on the <!-- slide --> markers in the chapter files, which stay invisible when the same file renders as a docs page.

Each code block carries a copy button in its top-right corner, the same affordance the docs pages have — it appears on hover, so a projected slide stays clean. Copying beats retyping a command with a UUID in it in front of a room.

Lines marked Presenter note render on the slide itself rather than in the speaker view — they are as visible to the room as everything else, so they carry timing and pitfall warnings, never anything you would not say out loud.

Every slide carries a coloured bar across its top edge and a pill in the corner naming the identity acting on it. See the hats below for what each colour means. The pill is drawn outside reveal's scaled slide area, so it is the same size on a code-heavy slide as on a title slide, and it shows in the overview grid and the speaker view too.

The same files read as ordinary pages in make docs-preview, so the deck doubles as a condensed runbook when nobody is presenting.

Before you present

The demo runs against the local dev stack, and two things about it will bite you on stage if you meet them for the first time live.

Bring the stack up beforehand, not during chapter 2. make dev builds every image and waits for a kind cluster to become ready; on a cold cache that is far longer than an audience will sit through. Bring it up before the room fills, then show the command in chapter 2 rather than running it.

Device-code tokens live one hour. A full fifteen-chapter run exceeds that, so the token you minted in chapter 2 expires somewhere around chapter 10 and the next call fails with a 401. Chapter 9 carries an explicit re-authentication slide for exactly this reason — take it even if nothing has failed yet.

Two more, less likely to bite but worth knowing:

• Chapters 10 and 11 each wait for a Resource to reach Ready. That is a poll loop of up to a minute or two of dead air. Have something to say, or provision the chapter 11 Node during the chapter 10 wait.
• Chapter 14 pulls ghcr.io/plexsphere/plexd:latest. Pull it beforehand; the GitHub container registry is slow from some networks.

The hats

Knowing which hat you are wearing is most of the story the deck tells, so every slide says it outright. Seven identities act across the fifteen chapters:

Hat	Identity	Chapters	What it is
🖥️ shell	nobody yet	1, 2	Before the first sign-in. The stack is coming up and there is no session to speak of.
🛡️ admin	admin@example.com in Acme Corp	2–14	Domain admin and auditor — the tenant hat, and the one you spend most of the demo in. Runs under the default plexctl profile.
🏗️ operator	operator@example.com, platform sign-in	8, 9, 11	The platform authoring grant: creates Clouds and Credentials, approves assignments. No Domain admin holds it.
👤 member	member@example.com in Acme Corp	8	An ordinary tenant member. Used once, to show a catalog is readable without an authoring grant.
🏢 beta	admin@example.com in Beta LLC	3	A second tenant, to show the same human is a different principal there.
🤖 machine	svc-deployer in svc-demo	7	A service identity holding a token file. No browser, no human, no profile.
🔌 node	a bootstrap token, then a node envelope	13	No CLI session at all — a credential presented straight to the API, which is what chapter 13 makes you do by hand.

Four of the seven are browser sign-ins: admin, operator, member, and beta. The tutorials sign in fourteen times; a continuous session needs these four, all of them using the dev password password. The member and beta sign-ins each cost a browser round-trip for a single point; both slides say so, and both are safe to skip when time is short.

The remaining three never sign in. shell is the absence of a session, machine authenticates non-interactively with client credentials, and node is a Node presenting its own credential — the distinction chapter 13 exists to make.

Two slides wear two hats at once, and their bar is split down the middle to say so: chapter 9 opens by refreshing both the tenant and the platform session, and chapter 13 issues a token as the admin and redeems it as the Node on the same slide.

The badge is not maintained by hand. Each chapter declares its identity where it changes, and tests/docs/training_deck_hats_test.go checks every plexctl command on every slide against the hat that slide claims to be wearing — a slide showing --profile operator under the admin badge is a red build, not a surprise on a projector.

What this deck leaves out

The condensation is deliberate and the drift gate makes it explicit: every command in a source lesson is either on a slide here or carries a recorded reason for its absence. The categories:

• The per-lesson preamble. Fifteen lessons re-export PATH and PLEXSPHERE_URL and re-read the Domain id. Chapter 2 does it once.
• Identifier re-derivation. Lessons recover PROJECT_ID, CREDENTIAL_ID, and BLUEPRINT_VERSION_ID by slug because they cannot assume a prior lesson's shell. In one session those variables are still set.
• Repeated arcs. Reach your Resource re-runs the whole credential request-and-approve flow from Assign a Cloud Credential against a second Project. Chapter 11 names it and moves on.
• Cleanup. Deleting a Label definition, revoking a service token, and deprovisioning the bucket are lesson hygiene. Chapter 10 keeps the bucket teardown, because watching a Resource leave is worth showing; the rest is gone.
• The Console. Nine lessons carry a browser walkthrough. This deck is CLI-only.

How the deck stays true

A slide may only show a command that exists, character for character, in the lesson it cites. That is not a convention — it is a test.

Each chapter declares its source lessons in an HTML comment, and tests/docs/training_deck_drift_test.go enforces three rules: every lesson on the learning path is claimed by exactly one chapter, every shell block on a slide appears verbatim in a declared source, and every shell block in a source lesson is either on a slide or listed at the foot of the chapter with a reason.

The third rule is the one that matters over time. Adding a step to a tutorial turns the build red until somebody either puts it on a slide or writes down why it does not belong there. The deck cannot quietly rot into a museum piece of commands that no longer work, and nobody has to remember to check.

See docs authoring conventions for the chapter contract a new lesson has to satisfy.