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 asource, and its notes end withSource: references/<topic>.md, one file per topic underreferences/, 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 inimplementation-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 inhow-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 inidp/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¶
- Edit the outline, in both languages. One message per slide; what is said goes in
notes, not on the screen. - Show the repository's own files, never copies:
codepoints to a file in the repository anddiagramto an SVG with<g data-part="...">groups (../assets/docs/landscape.svg). - Render it again and look at it at phone and desktop width:
make deck(withOUTLINE=storytellingfor the talk). The.htmlis generated and versioned: it goes in the same commit as the outline, and is never edited by hand. make deck-testruns 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.