# spikinglabs/rondel (version 1) Pack digest: `sha256:d651d9dec624ce3c0565c571b4a5fb96a61f75f06b83372d7c3d258d57850b0f`. This file holds the brief, assumptions, obligations and manifest. Each component's contract, schemas and tests are in their own file; read the ones you build. Raw files are under [files/](https://files.symbola.sh/packs/spikinglabs/rondel/files/), and the tarball holds everything. ## Components - [parts/backup-v1.md](https://files.symbola.sh/packs/spikinglabs/rondel/parts/backup-v1.md) (44 KB) - [parts/link-crypto-v1.md](https://files.symbola.sh/packs/spikinglabs/rondel/parts/link-crypto-v1.md) (26 KB) - [parts/meeting-v1.md](https://files.symbola.sh/packs/spikinglabs/rondel/parts/meeting-v1.md) (61 KB) - [parts/room-v1.md](https://files.symbola.sh/packs/spikinglabs/rondel/parts/room-v1.md) (21 KB) - [parts/series-v1.md](https://files.symbola.sh/packs/spikinglabs/rondel/parts/series-v1.md) (22 KB) - [parts/template-v1.md](https://files.symbola.sh/packs/spikinglabs/rondel/parts/template-v1.md) (21 KB) ## AGENTS.md # AGENTS.md This is a Symbolon spec pack. Build from it; do not look for the original source. 1. Read `BRIEF.md`: what the product is, its non-goals and priorities. 2. Read `assumptions/`: what you may take as true about the world. Don't build for cases they rule out. 3. Read `obligations.toml`: the decisions you must keep. Obligations marked `open` are yours to choose; ones marked `unchecked` are required although no check covers them yet. 4. Each component's full specification is `components//versions//`: `symbolon.toml` (the description), `schema.py`, `examples.jsonl` and `properties.py`. Where the description and an example seem to disagree, the example is what the original does. **Harness.** An implementation is a directory with `symbolon-impl.toml` (`symbola impl-init --contract components//versions/`). In Python, define `run(input)` returning the contract's output; in any other language, a program that reads one JSON input per line on stdin and writes `{"output": ...}` per line. A component whose `symbolon.toml` says `driver = "cli"` is a command line: build the real program and set `command` to it; symbola runs it once per check. **The product.** If `PRODUCT.md` exists, the pack is a whole product: build it as `PRODUCT.md` describes (its shape, surfaces and flows), with your component builds as its core. Don't build a demo page around the components instead. **Done** means `symbola attest components//versions/ ` reports PASSED for every component and, for a product pack, every flow in `PRODUCT.md` works. Don't special-case the examples: the properties generate other inputs, and the publisher keeps a holdout. Write questions about unclear parts, and the reading you chose, in `NOTES.md` next to your build. **If the spec contradicts itself**, don't code around it. Run `symbola flag #example: "" --dir `, build the reading you think is right, and carry on. ## BRIEF.md # Rondel Rondel is an end-to-end encrypted tool for team retrospectives and meetings, with no accounts: you share a link. People write cards, group, vote, discuss and agree actions (a retro), or run an agenda with a timer, shared notes, decisions and action items (any meeting). They can prepare before the meeting starts and carry open actions into the next one. A meeting can repeat daily, weekly or monthly behind one stable link. It is a static web app plus an optional, very small room server. Everything people write is encrypted in the browser with a key that lives only in the meeting link (after `#`), so whatever stores or relays the meeting cannot read it. Teams use it from their browsers; an organisation can run its own copy on Cloudflare, on any Node host or container, or as plain static files with browser-to-browser sync. A rebuild is only faithful if it **interoperates** with real Rondel: its links open real meetings, its encrypted updates and backups open in real clients (and the reverse), its room server speaks to real browsers, and meeting files, backups and templates saved by any earlier release still open. The components in this pack pin exactly those surfaces. `PRODUCT.md` says what the rest of the app is. ## Non-goals - Server-side search, reminders, integrations or any feature that needs the server to read meetings. The server must never see content. - Accounts, passwords or per-person permissions. Anyone with the full link can join and edit; facilitator controls and hidden vote totals are conventions in the app, not enforced. - Replacing the original's code layout, UI styling, animations or exact wording of interface texts and error messages. Interface languages beyond English are optional. - Real-time collaboration beyond what the document format gives: Yjs merges concurrent edits; there is no locking or turn-taking. - Hosting or billing. How an organisation deploys (Cloudflare, Docker) is its own concern; the pack only fixes what the server does. ## Priorities When goals conflict, earlier ones win: 1. Confidentiality: nothing readable leaves the browser; the link key is never sent anywhere; the server stores and relays only sealed data. 2. Compatibility: documents, encrypted updates, links, series rooms, backups and templates read and write exactly as real Rondel clients do, including everything earlier releases saved. 3. Meeting behaviour: the operations and rules in the meeting, series and template components, exactly. 4. The room-server protocol, auth check, limits and retention, exactly. 5. Working without a server (peer-to-peer) and offline: edits are never lost; they sync when possible. 6. The rest of the app (screens, flows, layout) as `PRODUCT.md` describes; styling is the builder's. ## Who resolves gaps spikinglabs, as the namespace holder. If the pack doesn't settle something, record the question and the reading you chose in `NOTES.md` next to your build; obligations marked `open` in `obligations.toml` are yours to choose. ## PRODUCT.md # Rondel: the product A build of Rondel is a **static web app plus a small room server**, not a set of libraries. The components (`meeting`, `series`, `link-crypto`, `backup`, `room`, `template`) are the exact core; this file says what surrounds them. Where it is silent (layout, colours, wording, animations), the builder decides. ## Shape - A single-page web app in the browser (React 19, Yjs, y-indexeddb for the local copy, Vite; installable as a PWA with a service worker that makes the app load offline). Routes live in the URL fragment (`#/...`), so the key in a link never reaches any server. Interface in English and German; the language follows the browser unless chosen. Light, dark or system theme. - All meeting data lives in the browser: one Yjs document per meeting (IndexedDB `rondel-`) and one per series (`rondel-`); small settings in `localStorage` under `rondel:`-prefixed keys: `me` ({id, name}), `prefs`, `meetings`, `series`, `templates` (YAML texts), `people`, `lang`, `layout`, `voter:`, `drafts:`, `mine:`. The backup file carries exactly these keys and documents. - Sync, decided once at start from `window.RONDEL_CONFIG.sync` (`auto` | `server` | `p2p`; a claude.ai preview adds `artifact`): in `auto`, `GET api/health` next to the app (or at `serverUrl`) answering JSON with `rondel: true` means room server, anything else (or a `file:` page) means peer-to-peer. With a server every change is sealed with the link-derived key and sent to it; without one, browsers connect directly (WebRTC through Trystero with Nostr or BitTorrent trackers as `strategy`, optional `relayUrls` and `turn`), with nothing stored anywhere, so a meeting exists only while someone who has it is online. - A **room server** speaks the `room` component's WebSocket protocol at `api/rooms/`, answers `GET api/health` with `{"rondel": true, "protocol": 1}` and serves the built app (unknown paths fall back to `index.html`; headers: assets cacheable for a year, `referrer-policy: no-referrer`, `x-content-type-options: nosniff`). It stores only sealed entries. Two adapters share one `Room`: - **Node 22.5+**: HTTP + WebSocket (ping every 25 s), meetings in one SQLite file (`node:sqlite`) per data directory. Settings by environment: `PORT` (8787), `DATA_DIR` (`./data`), `STATIC_DIR` (`./dist`), `RETENTION_DAYS` (90; 0 keeps meetings until deleted). An hourly sweep deletes rooms unchanged for the retention time and with nobody connected. Run exactly one copy. A Docker image runs it on `/data`. - **Cloudflare**: a Worker serves the app, one Durable Object per room (SQLite storage, WebSocket hibernation: idle open tabs cost nothing, `{"t":"ping"}` is answered with `{"t":"pong"}` without waking the room, an alarm enforces retention, `RETENTION_DAYS` in the worker variables; a rate limit of connections per address per minute). - Deployment settings live outside the code in a folder (`site.json` + optional `templates/*.yaml`) applied to a built `dist/` by `scripts/site-config.mjs`: it merges the settings into the `RONDEL_CONFIG` block of `index.html`, copies templates, and with `sync: "server"` adds a Content-Security-Policy allowing only the page's own files and its server. Settings: `name`, `sync`, `serverUrl`, `feedback`, `language`, `lab`, `robots`, `templates`, `operator {name, url, contact, hosting, retentionDays}`, `strategy`, `relayUrls`, `turn`, `shareUrl`. - No analytics, no third-party requests (the QR code is drawn in the browser; no online QR service). Markdown is rendered to elements, never as raw HTML; links open only `http(s)` and `mailto`. ## Surfaces Pages (hash routes; the dotted forms `#m..` and `#s..` are rewritten to them, as the `route` operation of `link-crypto` states): - **Name prompt**: shown before anything else (except `#/data`) until the person has entered a name; the name is remembered in this browser (at most 60 characters). - **Home** (`#/`): the list of this browser's meetings (title, kind, live or closed, open actions) and series, "Join a meeting by link", "Open meeting file…", "New meeting" with the template picker, the series form, "Design a meeting", preferences (name, theme, language, card and voting defaults, "Back up or restore…"), footer with language menu, "Run by ", feedback link, data page link. - **New meeting**: pick a template (built in, "From your organisation", "My templates"), optional title, create. Template cards offer **New version** (copy named "… (v2)"), **Edit** (my templates), **Copy**, **Download .yaml**. **Design a meeting** / **Design new…** open the designer: name, stages with minutes, activity, owner, notes and screen; columns; voting rules; a run of show with clock times and the `design_checks` warnings; a YAML tab editing the same template with errors by line; **Import .yaml…**. - **Meeting** (`#/m//`): top bar with title (double-click to rename), who is here, "I'm done" count, sync status, Invite, Minutes, Settings, command palette (Ctrl/⌘ K). Left: the agenda with the timer, "Next item", start/pause/resume/+1/+5 minutes, an item's notes. Middle: up to two blocks (board, brainstorm, discussion notes, action items, decisions, people), newest on top; every block has a fixed home in the right side bar and a ⤢ button to move it; layout remembered per browser in `rondel:layout`, a stage's `screen` applies when it starts. Board: columns with colours, private drafts then shared cards (or live cards on an open board), drag a card onto another to group, group names, votes with dots, full-screen column, stage buttons (1 Write … 5 Actions) for facilitators, "Reveal votes". Brainstorm: collect → vote (3 dots) → pick (to action or agenda). People: who is here now (here, writing, done) and who joined earlier; the creator can remove or allow back. Close / Reopen. Settings: title, card authors, vote limits, secret voting, open board, "Use these settings for my new meetings", "Save as a new template…", Delete from server… (facilitators; room servers only). - **Invite**: copy link, "QR code of the meeting link", "Link to this meeting only", invite text. - **Minutes**: formatted view with "Copy for email" (HTML with inline styles plus Markdown as plain text), "Copy Markdown", "Download .md". - **Series** (`#/s//`): resolves the current meeting (below) and shows "Opening the current meeting…", or the closed state with "Open it to read the minutes, or start another meeting this week." `#/s///overview`: all meetings of the series, facilitators ("Facilitate this series too"), invite text, "Download calendar file (.ics)", "Open next occurrence", "Delete series from server…". - **Data page** (`#/data`): plain-language statement of what is encrypted, what the server stores, what stays in the browser, what files contain, retention and deletion, the public relays of the peer-to-peer fallback, and "Check it yourself" (the `npm run verify` commands). Readable before entering a name. Keep it true. - **Error screen** with a reload button for crashes; `#/crash-test` shows it on purpose. - Files people touch: **meeting file** (`.json`, `rondel-meeting`), **backup** (`.json`, `rondel-backup`), **minutes** (`.md`), **calendar** (`.ics`), **template** (`.yaml`), `site.json`. Formats: see the components. - Server: `GET api/health`; WebSocket `api/rooms/` (8 to 64 URL-safe characters); static files. - Command line: `npm run build`, `npm start` (Node server), `npm run verify -- ` (checks that a site sends exactly the files of a build), `node scripts/uptime.mjs ` (app page, `api/health`, a real room). ## Flows 1. **Start a meeting.** Home → New meeting → pick a template → optional title → Create. The app makes a room id and link key (`link-crypto` `new_ids`), builds the meeting from the template with an unseeded start (`meeting` init; random ids), adds the creator as the first person (`join`), stores it locally and opens `#/m//` (`link-crypto` `link`). Outcome: an empty live meeting with the template's agenda, board and settings; the link is on the clipboard-ready Invite panel. 2. **Join and sync.** Opening a link (or pasting it into "Join a meeting by link"): derive keys from the fragment (`link-crypto` `auth`); with a server, connect to `api/rooms/` and send `hello` with `since` = the last stored seq the client has seen (`room`). The `welcome` entries are opened and applied to the local document; if the local document holds anything the server lacks (offline edits, a new meeting, an opened file) it is sent as an `upd`. Afterwards every local change is sealed and sent as `upd` with an increasing `id` (kept until acknowledged), others' changes arrive as `upd` and are applied, and presence goes as sealed awareness updates (`aw`) that are re-announced when someone joins. When the welcome says the log has more than 150 entries, the client sends `compact` with `upTo` = the last seq it has and a sealed snapshot of what the server is known to hold. The connection pings every 10 seconds and is dropped if nothing was heard for 25 seconds; it reconnects with back-off (1 s doubling to 30 s) or at once when the network returns. `forbidden`, `version` and `gone` errors are final: the screen explains (wrong link / reload / deleted) and nothing is retried. While offline everything is kept locally and sent after reconnecting. Outcome: everyone with the link sees the same meeting, live or later. 3. **Run a retro.** A facilitator starts the Write stage; people write private drafts, share them (cards `share_card`), then Group (`group`, `group_title`), Vote (`vote`, with limits) and Discuss (votes are revealed; cards in vote order), then Actions (`add_action`), then Close (`close`). "I'm done" counts people; everyone done shows a green mark. Outcome: minutes with the board, votes, notes, decisions, actions. 4. **Run an agenda.** "Next item" or starting an item makes it current and starts its timer (`set_current`); notes are shared text (`notes_insert`); decisions and actions are added; brainstorm items collect ideas, dots, and turn ideas into actions or agenda topics. Outcome: a record of each topic. 5. **Next meeting.** After closing: "Start the next meeting" creates a meeting with the same template and settings; open actions and unfinished extra topics carry over (`meeting` init with `previous`); the new meeting names the old one as `previousTitle`. Also possible from a saved meeting file ("Open meeting file…"). 6. **Recurring series.** Home → series form (name, repeats daily / weekly / monthly / irregular, template, optional first meeting time and length) → a series document is made (`series` `document`) and the series link `#/s//` is shown with invite text and the `.ics` (`series` `ics`). Opening the link: load the series document, compute the current period (`series` `period`, local date), decide (`series` `decide`): `open` goes to that meeting; `create` makes it with the room and key from `series` `room`, a meeting started from the series template with `seed` = that room id, the series' facilitators as facilitators, the `series` reference and title " – " (`series` `label`), and records it in the series document; `closed` shows the closed meeting with "Start another meeting this week" (the next free name). "Open next occurrence" prepares the next period's meeting (`next_after`). Titles and closed state are kept in step in the series document (`sync_occurrence`). Outcome: everyone with the link lands in the same meeting without a server telling them which. 7. **Delete from server.** A facilitator deletes a meeting: in a series the occurrence is first marked deleted in the series document (`mark_deleted`), then `delete` is sent; the other browsers are told, drop their local copy, and see that it was deleted. "Delete series from server…" deletes every meeting then the series document. 8. **Keep a record.** "Save meeting file" downloads `rondel-meeting` JSON (`{format, version: 1, roomId, key, title, exportedAt, update}`); "Open meeting file…" restores it as a meeting in this browser, merged if the meeting is already known. Minutes as Markdown or email HTML. 9. **Move browsers.** Preferences → Back up or restore… downloads a backup (`backup` `make`, with an optional passphrase); restoring in another browser (`backup` `read`, `merge`) adds lists and meetings, never removes any, and optionally takes over the person's identity so they stay a facilitator. 10. **Templates.** Write or import YAML (`template` `parse`, errors by line), design visually (the same template), save to "My templates" in the browser, download `.yaml`, "New version" (`new_version`), "Save as a new template…" from a meeting (`from_meeting`); organisations ship YAML in their `templates/` folder (listed in `RONDEL_CONFIG.templates`; a file that fails to parse is skipped with a console warning). The built-in templates are those of `template` `builtin`. 11. **Run your own copy.** Build, apply a `site.json`, run the Node server (or deploy the Worker), put HTTPS in front (browsers need it for the encryption except on localhost) and pass WebSocket upgrades on `/api/`. Retention deletes unchanged meetings after `RETENTION_DAYS`; a browser that still has a copy can upload an expired meeting again, but not a deleted one. ## Interfaces - **Room server** (above); the app also works against a server at another address (`serverUrl`). - **Peer-to-peer relays** (public Nostr relays or BitTorrent trackers, optional TURN) are used only when no server answers or `sync` is `p2p`; with `sync: "server"` the app never contacts them. - **claude.ai artifact** (optional): inside a preview with the `db`, `room` and `downloads` capabilities the app stores and syncs through them and invite links use the dotted form with `shareUrl`. - No credentials in the app. Deployment secrets (Cloudflare API token and account id) belong to the release workflow only. ## Order If a build cannot do it all, build in this order: (1) the six components; (2) the Node room server; (3) the browser app against a server: home, new meeting, join, sync, meeting screen with agenda, notes, cards, votes, actions, decisions, close, minutes; (4) templates and the designer, meeting files; (5) series and calendar invites; (6) backup and restore; (7) retros' stages, brainstorm, command palette, layout; (8) peer-to-peer fallback, PWA, German, Cloudflare adapter, the data page and the release tooling. ## assumptions/compatible-clients.toml ```toml id = "K-compatible-clients" statement = "Every client of a room speaks the same protocol version, and uses a Yjs implementation that reads and writes the same v1 update encoding as Yjs 13." basis = "The server refuses other protocol versions (hello v must equal 1). Saved meeting files, backups and server entries all hold Yjs v1 updates, written by earlier Rondel versions." monitor = "The server answers a hello with another protocol version with the error code version; saved files carry a format and version." ``` ## assumptions/device-clocks.toml ```toml id = "K-device-clocks" statement = "The devices in a meeting have clocks that agree to within a few seconds, and show the same calendar date at the same moment." basis = "The timer stores an absolute end time taken from the starting device's clock, and a series computes its current period (day, ISO week, month) from each person's local date, so people in time zones far apart can compute different periods around midnight." monitor = "none" ``` ## assumptions/link-stays-private.toml ```toml id = "K-link-stays-private" statement = "Only the people meant to be in a meeting ever have its full link (the part after #), and the link is never sent to anything that logs or stores URLs with fragments." basis = "The key is the fragment of the link, which browsers do not send to servers; everything else (encryption, the server proof, retention) assumes nobody outside the meeting holds it. Facilitator controls are a convention, not enforced: anyone with the link can edit." monitor = "none" ``` ## assumptions/names-are-free-text.toml ```toml id = "K-names-are-free-text" statement = "People's names are free text, not unique and not verified; a person is identified by a random id kept in their browser." basis = "No accounts. The identity is {id, name} in localStorage; the creator is the person whose id is in meta.createdBy." monitor = "none" ``` ## assumptions/one-server-process.toml ```toml id = "K-one-server-process" statement = "At most one room-server process serves a given set of meetings: open meetings live in that process's memory and its SQLite file has a single writer." basis = "DEPLOY.md says to run exactly one copy; the Node server keeps a Room object per open room, and the Cloudflare version uses one Durable Object per room." monitor = "none" ``` ## assumptions/secure-context.toml ```toml id = "K-secure-context" statement = "Rondel runs in a secure browsing context (HTTPS, or localhost), where the Web Crypto API (HKDF, AES-GCM, PBKDF2) is available." basis = "The app encrypts everything with crypto.subtle, which browsers only offer in secure contexts. DEPLOY.md says to put the server behind HTTPS." monitor = "none" ``` ## assumptions/small-meetings.toml ```toml id = "K-small-meetings" statement = "A meeting is small: a few dozen people, at most 100 open connections per room, and far less than 25 million characters of stored updates, because clients compact the stored log long before the limit." basis = "The server enforces the 100-connection and 25,000,000-character limits as hard errors; the client compacts after 150 stored entries. Typical meetings are text of a few kilobytes." monitor = "none" ``` ## obligations.toml ```toml # Obligations of the spikinglabs/rondel spec pack (format: docs/PACK_FORMAT.md). # # Each obligation is one decision a builder could get wrong, with the checks # that pin it down. status: decided (required), default (chosen; a fork may # change it with a note), open (deliberately undecided; builds may differ). # Checks are "#example:" or # "#". A required obligation no check can # express yet has checks = [] and unchecked = "". [[obligation]] id = "meeting.title" statement = "A new meeting's title is the explicit title (trimmed), else the template's title with `{date}` (the day, ISO) and `{month}` filled in, else `