An AI-collaborative presentation protocol owned and developed by EdProAI. This document is the canonical contract for how a deck conforms to v1: how it's authored, how humans consume it in the viewer, and how AI agents round-trip critique back into the live discourse.
tldr/v1
Reference impl: Stages platform-website
chris@teachupbeat.com
Every conformant 2ldr; deck honors all eight. These are not aspirations — they're how each surface decision gets made. If a feature violates one, it doesn't ship.
The top-level deck object, the slide object, and the sanitization rules every renderer must apply.
Required fields are unmarked. Optional fields are noted as // optional in the comment. The notes_endpoint is the only network dependency in v1.
{
"protocol": "tldr/v1", // required, exact string
"title": "string", // required, deck title
"subtitle": "string", // optional, appears next to title in chrome
"generated_at": "ISO 8601", // required, UTC timestamp of deck creation
"reviewers": ["string", ...], // required, predefined reviewer names (humans)
"branding": { // required
"name": "2ldr;", // brand mark
"by": "EdProAI", // platform owner
"license_orgs": ["string", ...] // permitted orgs (footer modal)
},
"boarding_pass": { // optional but recommended
"enabled": true,
"coach_options": ["risk", "voice", "missed", "pushback", "overconfidence"]
},
"glossary": { ... }, // optional, term → {plain, tech, link}
"slides": [ ... ],
"slide_tldrs": { ... }, // optional, per-slide TL;DR pill content
"notes_endpoint": { // required
"url": "https://...",
"profile": "<deck-slug>-notes",
"auth_header": "x-my-cache-key",
"auth_value": "..." // public — viewers post; rate-limited server-side
}
}
{
"id": "kebab-case-id", // required, unique within deck
"num": "01", // required, zero-padded
"title": "string", // required, slide title
"type": "hero|conventions|tldr|stack|why|phases|reqs|risks|code-style|ack|open-mic|agenda|wrap|custom",
"body_html": "string", // required, sanitized HTML; uses design tokens
"plain_only_html": "string", // optional, plain-mode-only content
"tech_only_html": "string", // optional, tech-mode-only content
"glossary_terms": ["..."] // optional, terms to auto-link in body
}
p, div, span, h1-h6, strong, em, code, pre, ul, ol, li, a, br, hr, table, thead, tbody, tr, th, td, blockquote, kbd, i, b, sup, sub, dl, dt, dd, figure, figcaption, img
class, id, href (http/https/mailto only), src (http/https/data:image only), alt, title, target, rel, aria-*, data-*, lang, role
<script>, <style>, <iframe>onclick=), javascript: URIs, inline style=How discourse flows on a 2ldr; deck. Endpoint contracts, agent rules, threading, and the agenda surface.
POST {notes_endpoint.url}?profile={profile}
Headers:
x-my-cache-key: {auth_value}
Content-Type: application/json
Body:
{
"comment": string, // ≤280 chars protocol cap
"view": "plain" | "tech",
"slideId": string,
"reviewer": string, // human name
"createdAt": ISO 8601 UTC,
"parentId": string // optional, threading
}
GET {notes_endpoint.url}?profile={profile}
Headers:
x-my-cache-key: {auth_value}
Response:
[
{
"id": "<uuid>",
"slideId": "<slide-id>",
"view": "plain" | "tech",
"reviewer": "<name>",
"comment": "<body>",
"createdAt": "<ISO>",
"parentId": "<uuid>" // replies only
}, ...
]
These rules apply to AI authors only. Humans post freely.
slideId: X, they cannot post to X again until another author posts there. Interleaving with humans is the discipline.overflow_capture in §2.1) and reference the entry ID from the 280-char deck post.[ai] ai, close-bracket, space. Reviewer name stays human (no .AI suffix). Deck strips prefix and flips the human/AI pill to violet.view deliberately[ai] always first, urgency second: [ai] [urgent:high] <body>.A reply points at a parent via the optional parentId field. Replies render nested below their parent, smaller (13.5px vs 16px) and indented by ~24px with a left-edge accent in the parent author's color.
parentId is optional. Notes without it are top-level.parentId MUST reference an existing note in the same profile. Orphans surface as malformed-state warnings.slideId as its parent. Cross-slide threading is invalid.Prefix the comment with [urgent:high], [urgent:medium], or [urgent:low] followed by a space. The viewer parses the marker on render, strips it from the displayed body, and shows a colored urgency badge.
How the agent that ate the downloaded 2ldr.md keeps itself in sync as new notes, agenda items, and votes land on the live deck.
Track a last_seen_created_at watermark per profile. On each poll: GET the full notes set, filter to createdAt > last_seen_created_at, ingest the filtered items, update the watermark.
Coverage must include all three agenda slideIds — they're separate logical streams in the same profile. An agent that polls only top-level notes misses the talking-points and the vote signal.
# Poll the deck for new activity. Defaults to a 120s cadence. # Set LAST_SEEN to the most recent createdAt your agent has already ingested. LAST_SEEN="${LAST_SEEN:-1970-01-01T00:00:00Z}" while true; do RESP=$(curl -sS "$CACHE_ENDPOINT?profile=$PROFILE" \ -H "x-my-cache-key: $CACHE_SECRET") NEW=$(echo "$RESP" | jq --arg ts "$LAST_SEEN" \ '[.[] | select(.createdAt > $ts)]') if [ "$(echo "$NEW" | jq 'length')" -gt 0 ]; then echo "$NEW" # or pipe to your agent's input LAST_SEEN=$(echo "$RESP" | jq -r 'max_by(.createdAt).createdAt') fi sleep 120 done
The CACHE_SECRET is embedded in the downloaded 2ldr.md by design. The my-cache endpoint enforces rate limits and write quotas server-side; the secret is the application identity, not a per-user credential. Agents do not need a separate read key.
For sandboxed agents (Claude.ai web, ChatGPT) with no HTTP/curl access. The user clicks once; the deck applies the post under their identity.
[ai] prefix and any urgency marker.localStorage['2ldr-seen-post-ids'] (capped at 200 entries).id, slideId, view, comment. The reviewer field is intentionally omitted — the deck always uses the clicker's STATE.reviewer, preventing forged-author URLs.<deck-url>#2ldr_post=<base64>. CloudFront signed URLs hash the query string, so ? params break the signature and produce HTTP 403. Fragments bypass server signing entirely.history.replaceState.| Attack | Defense |
|---|---|
| Forged-author link | Impossible — the deck never trusts a reviewer field in the payload, always uses the clicker's boarded identity. |
| Replay | UUID dedupe via localStorage + fragment stripping after first apply. |
| Wrong-deck link | Harmless — payload validates against the slide enum; unknown slideId values are silently rejected. |
| Schema injection | Required fields validated (id, slideId, comment); malformed payloads rejected. |
How the deck learns who's reviewing it, and how the absorbing agent gets enough context to be useful.
When boarding_pass.enabled is true, the deck captures four fields locally. Boarding is private to the browser — no network POST. The downloaded markdown is the only export path.
| Field | Type | Stored where | Used for |
|---|---|---|---|
name | string | localStorage[deck-reviewer] | Note attribution + color signature |
role | string | deck-boarding-profile.role | Get-my-take prompt + downloaded markdown |
lens | string | deck-boarding-profile.lens | Get-my-take prompt + downloaded markdown |
coach[] | string[] | deck-boarding-profile.coach | Get-my-take prompt + downloaded markdown |
Every conformant deck must expose a "Get the 2ldr.md" affordance that emits a single markdown file containing:
Three sets of guardrails: declaring conformance, naming the license scope, and version-locking.
<meta> declarations<meta name="tldr-protocol" content="tldr/v1"> <meta name="tldr-protocol-conformance" content="full" | "partial"> <meta name="tldr-protocol-author" content="EdProAI">
| Version | Meaning |
|---|---|
v1.0-draft | Current. Surfaces still moving; spec is reference-only. |
v1.0 | Locks once the Stages platform-website deck (canonical reference impl) is approved by Angela's team. |
v1.1+ | Minor additions (new optional fields). Backwards-compatible. |
v2.x | Breaking changes. The protocol field in the deck object MUST match the spec version the deck conforms to. |
Hard rules. Violations are conformance failures, not preferences.
2ldr; (lowercase, semicolon). The abbreviation "TL;DR" is the distillation concept — kept distinct. Brand surfaces never collapse to "tldr;" or "TLDR;".tldr/v1 in the deck object's protocol field. Tooling reads this string; humans read the brand.[ai] prefix on the comment text. Reviewer name stays human — no .AI suffix.#2ldr_post=<base64> fragment, never ?2ldr_post= query. CloudFront signed URLs depend on this.b, i, strong, em, code, a, br + <span> with class only. NO scripts, NO inline styles, NO event handlers, NO javascript: URIs.slideId='agenda' to prevent duplication with the agenda-items body.STATE.reviewer === 'Chris'. Real auth is a future Wave.body_html are a v1 conformance violation. Use the design tokens (cosmic-neon CSS custom properties).