Skip to content

Deck

The project as presentations, each rendered from one outline by render-outline, in the reference style of the How I use AI deck (how-i-use-ia.yaml, #461): one slide at a time, phone first, bilingual (English and Portuguese), light and dark themes; big titles with one amber accent, spaced uppercase labels, plain lists revealed in turn with the previous item dimmed, the source at the bottom, and the references in a deck of their own. The rules for whoever writes a deck are in docs/agent/decks.md.

  • nereus.yaml: the idea, the model (reef, Nereid, Mandate), the first slice and where it is heading.
  • storytelling.yaml: the talk before the platform, the same problems for fifty years and the question for the AI era (#190). Every fact on screen has a source, and its notes end with Source: references/<topic>.md, one file per topic under references/, which the renderer turns into a link.
  • how-we-work.yaml: how the work happens in this repository, for people who build software with AI: what already existed and what the agent changes (#882).
  • release.yaml: the release reef step by step: its four kinds, the nine commands that run a Helm chart through the flux Nereid, the HelmRelease it writes underneath, and swapping the tool (make deck OUTLINE=release).
  • implementation-comparator.yaml: two Nereids of the same reef measured side by side by performance, satisfaction and cost, and the comparator Nereid that turns the comparison into a decision (Keycloak and Auth0 in the authentication reef); its code frames and diagrams, one per language where they differ, are in implementation-comparator/ (#1457).
  • more-than-an-idp.yaml: the pitch, Nereus as more than an IDP in fourteen slides: an IDP is one profile of a composable platform API, swapping the tool changes no command, the comparator as the example, agents as clients and peers, and how the work happens; it ends asking for a pilot of the comparator (#1487).
  • how-i-use-ia.yaml: how I use AI, one real night told in eight acts and an appendix: the reference style of the decks (#461), first built by hand and rendered from its outline since #1458; its diagrams and the files it shows, one per language, are in how-i-use-ia/.
  • idp/: the Internal Developer Platform series, ported from the first proof of concept (wasp-idp, #538), one deck per part (make deck OUTLINE=idp/problem); its sources are in idp/references/.

One page is built by hand, not rendered from an outline: doris-demo.html, the replay of a thread of notes, a page that browses data (docs/agent/decks.md), until the ideas reef's portal (#1108) takes it.

See it

make deck

It renders nereus.html and opens it; make deck OUTLINE=storytelling renders and opens the talk. F11 for full screen.

Key Action
↓ Enter Space PgDn Next step: the next item, else the next terminal step, else the next diagram part, else the next slide
↑ Back one step: hides the last item shown, else restarts the slide; at the start of a slide, the previous slide
← PgUp / → Previous / next slide, skipping the steps
Home The first slide of the deck
D The reference deck, and back
I The slide index, and closes it; in it, ↑ ↓ walk the entries and Enter goes to one
N / L / R / C Notes / language / restart the slide / every item at full colour
+ / - Larger / smaller text, terminals included
O Hosted by the Sessions tab, in full screen: the room's turn on offer, the slide's question or the rating (#1882)
Esc Close the QR code, else the index, else the notes

The top bar has the deck's name, the theme (it follows the system until tapped, then swaps light and dark), the language (EN | PT, the chosen one highlighted) and the counter (R before it in the reference deck); a tap on the counter opens the slide index (#1450): one entry per slide of the deck on screen (its number, label and message, in the language on screen) under its act's title, the current one marked and in view; a tap on an entry goes to that slide, at its start, and a second tap on the counter, the close button or a click outside closes it. The bar at the bottom has home, previous, A−, A+, the notes, References (Back to the deck from there) and next. On a phone, a round navigation pad sits above it (▲ back one step, ▼ next step, ◀ ▶ slides, ↺ restart, ☀ every item at full colour), dims when idle and moves when dragged by its edge; a swipe to the left is the next step, to the right the previous slide. The notes open in a panel with their own A− and A+, and a click outside closes them; a QR code opens in an overlay with its link, and a click outside closes it. The deck remembers the slide, the language and the theme in the browser. A link to one slide: nereus.html#<name>, the name of the slide in the outline (#ref-<name> for a reference).

Change it

  1. Edit the outline, in both languages. One message per slide; what is said goes in notes, not on the screen.
  2. Show the repository's own files, never copies: code points to a file in the repository and diagram to an SVG with <g data-part="..."> groups (../assets/docs/landscape.svg).
  3. Render it again and look at it at phone and desktop width: make deck (with OUTLINE=storytelling for the talk). The .html is generated and versioned: it goes in the same commit as the outline, and is never edited by hand.
  4. make deck-test runs the renderer's tests, including the validation of both outlines and a fresh render compared with the committed decks.

The portal mode

A committed deck is one self-contained HTML file, the offline export. The portal serves its pages under default-src 'self', which refuses an inline <style> and <script>, so render-outline --split writes the same deck as an HTML that links deck.css and deck.js, written next to it from the same CSS and SCRIPT (#1693). Nothing else differs: no style attribute, event-handler attribute or eval is left in either mode, and the script styles only through the CSSOM, which the policy allows.

uv run --with pyyaml --with segno python render-outline storytelling.yaml --output /tmp/deck/storytelling.html --split

make deck-test checks it in headless Chromium: two decks in the portal mode, served under the portal's own csp() (controllers/nereus-portal/portal.py) and walked through every slide and step, raise no CSP violation. The test uses Playwright's Chromium when it was downloaded, else the Chrome of the host.

Steps and followers

A step is what one press reveals, counted with no animation (#1760): a slide at its start, then each item (.st, the cover's subtitle included), a terminal command's two presses (typed, then run), each further line of a stepwise output, and each part of a diagram's reveal. The renderer writes each slide's count as data-units, and render-outline <deck> --steps prints the deck's total; tests/test_steps.py walks every deck with the animations off and checks that each press is exactly one step.

The engine reports every move as a nereus-step event ({step, steps}) and goes to a step on nereus-goto ({step}): the next step animates as a press does, any other is reached at once. html[data-mode="follow"] is the follower's mode (the portal's /p/<code>, which loads the portal's copy of deck.css and deck.js): the controls that change the step are hidden and ignored, and A−/A+, the theme, the language and the animations (the M key or the pill, kept per device) stay. After a change of the engine, copy deck.css and deck.js from a --split render into controllers/nereus-portal/static/; make deck-test fails while they differ.

html[data-mode="drive"] is the speaker's mode (#1761): the presentations reef's Sessions tab frames the portal's /present.html, which gets the Session's page with the notes from the tab by postMessage and holds no token. Every control stays; the page that hosts the deck sets the first step, so the engine neither starts from nor writes the address's hash or the browser's remembered slide. Each nereus-step goes back to the tab, which posts it as the Session's step, and a nereus-clock event ({text, over}) puts the talk's time in the top bar. In full screen, while the room's pace thermometer is on, a nereus-pace event ({show, slow, fast, text, label}, #1922) puts its counts after the clock in the bottom bar, as the host writes them (▲ 1 ▼ 2: up too fast, down too slow), its sentence as the label.

The outline

Its JSON Schema (#1700): one per outlineVersion, cli/src/nereus/schemas/presentations/outline/<version>.json. Version 1 is every field below but poll; version 2 is version 1 with a slide's poll (#1722), and a deck at 1 with a poll is refused with a message to raise outlineVersion to 2. A deck names its schema with $schema (a URL or a path, for an editor) and may name its version with outlineVersion (1 when absent); every deck of the repository validates against it (tests/test_outline_schema.py). nereus presentations schema get [<version>] prints it with no instance, the latest when no version is given, and the Nereus API serves it with no token on GET /v1/presentations/schemas/outline/<version>.json. What a schema cannot say (a pt for every text, links, files, fitting the screen) is the renderer's validation here and the Nereid's dry run (#1702).

At the top, deck (name, title, subtitle, and an optional accent: the words of the subtitle in amber on the cover), acts (name, title, an optional question that opens the act on its own slide unless opening: false) and references. Every text has its Portuguese version in a pt: block next to it, with the same field names; the validation refuses a missing one and an unknown field.

Slide field Required Meaning
name yes Stable slug of the slide, used by dependsOn and in links
act yes The act, from the acts list
topic no Shown after the act in the label: "Act · topic"
message yes The one idea of the slide, one sentence with no full stop, shown as the big title
accent no The word or words of the message in amber, at most one per slide; with its pt.accent. It must be in the message and must not cut through other markup; a cover takes deck.accent instead
heading or subtitle no The line under the message, revealed after it as its own step (at once with animations: none)
cover no true: the deck's title at once, then its subtitle, in place of the message
screen no Items of a plain list, revealed one at a time with the previous one dimmed (animations: none shows them at once); **Label:** text; a list that does not fit continues on the next slide; an item that starts with - is a sub-item of the one before, revealed on its own
terminal no {cwd?, steps: [{comment?, run, options?, output?, stepwise?}]}: run is the command with no options, options the long options, one per line, output what it prints, streamed by itself, or with stepwise: true one line per step, a blank line going with the line after it (#1456): a line that starts with ✓ or ✗, or Next steps:, takes its colour whole; in any other, ✓ is green, ✗ red, a lone ~ amber, {nereid:auth0} (any concept) takes its colour and {dim:...} the comment grey, the only place {dim:...} is allowed (#1455)
code no {file, lines?, focus?}: an editor frame on a repository file; focus dims the other lines
diagram no An SVG with parts. show: parts at full colour; dim: parts faded; reveal: one new part per step, earlier ones dimmed unless accumulate: true. Its viewBox gives its height on a phone, so the items that fit beside it stay on its slide (#1458)
pt.terminal, pt.code, pt.diagram no The Portuguese version of a frame whose text changes with the language, with the same parts; without it, both languages share the frame (#1457)
details no Per part of the diagram, {title, tip, body}, also under pt: the tip shows under the mouse, a click, a tap or Enter opens the title and body in an overlay
source no A "Source: ..." line at the bottom of the slide
refs no The names of the slide's sources in references: links to their slides in the notes
notes yes What the presenter says, not on the screen; the first sentence of each paragraph in bold
dependsOn no Slides that must come before (the chain of the argument)
status no A command's state in the CLI's specs (docs/specs/cli, #477): built, planned or idea, a tag after the label
issue with planned The issue that builds the command, shown in the tag (planned #475)
poll no, outlineVersion: 2 A question to the room (#1722), opened and closed by the speaker from the drive screen (#1917), named by the slide's name: {kind, question, choices?, scale?, seconds?, pt: {question, choices?}}. kind is choice (2 to 6 choices, lettered A to F, with as many pt.choices), scale (scale: {min, max}, integers from 0 to 10, min below max) or text (a few words from each phone, never shown on the projector); seconds is a reference time to answer, 5 to 300, 30 when absent: it closes nothing, the speaker closes the poll (and may reopen it, the answers in stay), and past it the drive screen counts the time over (+0:12) while the phones and the projector only say it is open. The slide shows the question and its options at once, no steps, with no screen, frame or cover; the message is optional, and with none the question is the slide's title. The poll's <div class='poll'> carries data-poll (the name), data-kind, data-seconds and data-choices or data-min and data-max, and an empty [data-poll-live] place (data-poll-clock, data-poll-count) and per option a data-poll-bar and data-poll-votes that a live session's screens fill. nereus presentations create --dry-run names the polls: 2 polls (level: scale 1-5, 30s; next: choice, 3 choices, 20s)

Inline markup on a slide: **bold**, _emphasis_ (italic, in amber in a title), `code`, [text](href) (a link; one to another deck's slide, ../specs/cli/reefs/edge.html#zone-create, must reach a slide of that deck, #477) and {reef:environment}, {nereid:vcluster}, {mandate:vcluster}, {secret:...} in the concept's colour; the roles of the work take theirs the same way: {order:...}, {pr:...}, {agent:...}, {raw:...}, {human:...}, {handoff:...} (#1458), and an SVG uses them as var(--cx-order) and so on.

References

references holds one entry per source, and they make a deck of their own, opened with the References button or D: a slide lists them, each with its QR code, and each one gets its own slide with the source, About:, For this talk: and its link next to its QR code (generated at render time with segno, inline, no network). A tap on a QR code opens it large in an overlay, with its link. The notes of a slide link to its refs, each with its QR code.

Field Required Meaning
name yes Stable slug, used by refs
title yes The source's title
url yes http(s): what the QR code opens
author, year no Shown under the title
about no The source in two or three sentences
forUs no What matters in it for the talk, with the exact quote when there is one

The validation refuses an unknown refs entry, a reference with no title or a non-http(s) URL, a name defined twice, and a reference no slide cites.