# Linked notes ## What this builds A web app for writing notes in Markdown and linking them together into a personal knowledge base. A person signs up and gets a **vault**: a tree of folders, Markdown notes and attachments. They write in an editor that hides Markdown syntax while they type (live preview), link notes with `[[double brackets]]`, and see for any note which other notes link to it. Tags, properties, full-text search with operators, a quick switcher, a command palette, a force-directed graph of the links, daily notes, templates, tabs and split panes, bookmarks, and image attachments are all included. Notes sync between the person's devices through the server. It is one Cloudflare Worker. The React single-page app is the Worker's static assets, the JSON API runs in the Worker, notes and the link/tag/search index live in one D1 database (SQLite, with FTS5 for search), and attachments live in one R2 bucket. It runs on a laptop with `npm install` and `npm run dev` (`wrangler dev`, local D1 and R2, no Cloudflare account), deploys with `npm run deploy`, and needs no other service. Read `spekkr.inputs.json` first. `app_name` is the product name (page title, sign-in page, Settings > About). `accent_color` is the accent colour (links, selection, active items, primary buttons, focus rings). `seed_demo` turns the demo vault in `design.md` ("Demo data") on or off. `access` (`only_me`, `invite_only` or `open`; default `only_me`) says who can create an account (R24). `cloudflare_access` (default off) adds the Cloudflare Access deploy steps to the README and turns off workers.dev and preview URLs (R24). `design.md` has the stack, Cloudflare config, data model, API, the parsing and link rules in full, the sync protocol, every screen and the look. `tasks.md` is the build order. `research.md` records what the design was modelled on; the builder does not need it, and nothing in it is a requirement. ## Names and words - The product is called `app_name` everywhere. The built app never shows the name, logo, icons or wording of any other notes product. - Interface text the spec quotes is the text to use. Other text is the builder's own, short and plain. - No image, font or icon file is copied from anywhere. Icons are inline SVG drawn in the app's own code. ## Words used here - **Vault**: one person's collection of files. A person can have several. - **File**: a note (`.md`), a folder, or an attachment (image, audio, video, PDF). Every file has a vault path like `Projects/Launch plan.md`. - **Note name**: the last path segment without `.md` (`Launch plan`). - **Link**: `[[target]]`, `[[target|shown text]]`, `[[target#Heading]]`, `[[target#^blockid]]`, or a Markdown link `[text](path.md)`. **Embed**: the same with `!` in front; the target is shown inline. - **Resolved / unresolved**: whether a link's target exists. - **Backlink**: a link from another note to this one. **Unlinked mention**: the note's name (or an alias) written as plain text in another note. - **MB**: 1,048,576 bytes (so 1 MB = 1,048,576 bytes, 20 MB = 20,971,520 bytes, 25 MB = 26,214,400 bytes). - **Owner**: the first account created on the site (the demo account never counts). **Member**: any later account. ## Out of scope Plugins and themes from others, canvas boards, database views, publishing, sharing a vault with other people, end-to-end encryption, version history (beyond the trash), PDF annotation, vault-wide block search (`[[^^`), updating links when a heading is renamed, excluded-files rules, offline editing across reloads (edits made while offline are kept in memory and sent when the connection returns). ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Run and store - Cloudflare Workers only. Worker code uses Web APIs (`fetch`, `Request`, `Response`, `crypto.subtle`, `crypto.getRandomValues`, `Intl`, `TextEncoder`) and no Node.js built-in (`node:*`, `fs`, `Buffer`, `process`); no `nodejs_compat` flag. - `wrangler.jsonc` (exact shape in `design.md`) serves `dist/` as static assets with single-page-app fallback, runs the Worker first for `/api/*`, binds D1 as `DB`, R2 as `FILES`, declares vars `NOW`, `TEST_CLOCK` and `ALLOW_SIGNUP` (R24), and turns on observability. - `npm run build` builds the client with Vite. `npm run dev` builds, applies migrations to the local D1 and runs `wrangler dev`. `npm run deploy` builds and deploys. The README gives the one-time deploy steps. - Schema in `migrations/0001_init.sql` and `migrations/0002_access.sql` (R24); the Worker never creates tables. Note text is stored in D1 (up to 1 MB per note). Attachment bytes are stored in R2 (up to 20 MB each); D1 keeps their metadata. - Clock: `NOW` (ISO time) freezes the server clock when set. When `TEST_CLOCK` is `"1"` a `test_now` cookie overrides it per request. The client asks `GET /api/now` and keeps the offset, so dates (daily notes, template dates, conflict copies) follow the server clock in the browser's time zone. Accept when: a fresh clone runs with `npm install` and `npm run dev` without a Cloudflare login, `wrangler deploy --dry-run` bundles with no Node.js compatibility warnings, and `GET /api/now` returns `NOW` when set. ### R2. Accounts and vaults - Sign up (when R24 allows it) with name (1–80 characters), email and password (8–200 characters). Emails are compared lower-case; a second account with the same email gets "That email already has an account". Sign in with email and password; a wrong pair gets "Email or password is wrong" (same text for an unknown email). Sign out ends the session. - Sessions: a random token in an `HttpOnly`, `SameSite=Lax` cookie that is also `Secure` on every host except `localhost` and `127.0.0.1` (plain-http local development); the database keeps only its SHA-256. 30 days. - Passwords: PBKDF2-SHA256, 100000 iterations, 16-byte salt. - A new account gets one vault named "My notes" holding a short "Welcome" note. The person can create more vaults, rename them, switch between them (the vault id is in the address: `/app?vault=ID`) and delete one by typing its exact name; the last vault cannot be deleted. Deleting a vault removes its R2 objects. - Settings > Account: change name, change password (needs the current one), sign out. - Every `/api/vaults/:v/...` request checks the vault belongs to the signed-in person, else 404. Signed-out requests get 401 and the client goes to `/login`. Requests that change data with an `Origin` header from another site get 403. Accept when: the R2 tests pass (sign-up, duplicate email, bad password, sign-out guard, vault create/switch/delete-confirmation) and the unit test "Access and cookies" passes (the Secure rule). ### R3. File explorer - Left sidebar tab "Files": the vault tree, folders first then files, each level sorted by the chosen order (name A→Z, Z→A, modified new→old / old→new, created new→old / old→new; saved on the device). Attachments show their extension as a small badge. The active file is highlighted. - Toolbar: New note, New folder, Change sort order, Expand all / Collapse all. - New note creates `Untitled.md` (or `Untitled 1.md`, `Untitled 2.md`... if taken) in the default location (Settings > Files & links: vault root, the current file's folder, or a chosen folder), opens it and selects its title so typing renames it. - Context menu on a file: Open in new tab, Open to the right, Rename…, Move file to…, Make a copy (notes), Bookmark, Copy path, Delete. On a folder: New note, New folder, Rename…, Move folder to…, Bookmark, Delete. - Rename: from the context menu, F2, or by editing the title above the note. Names cannot contain `\ / : * ? " < > | # ^ [ ]` or start with `.`, and cannot be empty; refused names keep the old name and show "Names cannot contain any of \ / : * ? " < > | # ^ [ ]" (or the matching message). A name already used in that folder (compared without case) is refused with "A file with that name already exists". - Drag a file or folder onto a folder (or the empty area for the root) to move it; a folder cannot move into itself. Dragging files from the computer onto the tree uploads them there (R19). - Keyboard: arrow keys move through the tree, Right/Left open/close folders, Enter opens, F2 renames, Delete deletes. - Delete asks first. By default deleted files go to the trash (Settings > Files & links "Deleted files": Move to trash / Permanently delete). Settings > Trash lists them with Restore and Delete, and Empty trash. Restoring to a taken path picks a free name. Deleting a folder deletes what is in it. Accept when: the R3 test passes (create, free names, invalid name, folder, drag move, F2 rename, duplicate refused, trash and restore, folder delete). ### R4. Editor and view modes - Each note tab has three modes: **Live preview** (default), **Source mode** and **Reading view**. The title bar has a button that switches between reading and editing (Ctrl/Cmd+E); the "More options" menu and the status bar switch live preview / source. Settings > Editor "Default view for new tabs" picks the mode new tabs start in. - Live preview is a CodeMirror 6 editor that renders Markdown in place: headings sized, bold/italic/strikethrough/highlight/inline code styled with their markers hidden except on lines that contain the cursor or selection; links show only their text; checkboxes are clickable; horizontal rules, bullets and block quotes are drawn; embeds are shown inline below their line; the properties block at the top is hidden from the text and shown as the Properties panel (R9). Source mode shows the raw text in a monospace font. - The properties block is hidden from the moment the note opens, wherever the cursor is (it is never revealed by the cursor, unlike inline syntax). A note opens with the cursor at the start of the body, just after the block, and a cursor that would land inside the block (arrow keys, undo, a click above the first line) is put at the start of the body instead. Only Source mode and the "Properties in document: Source" setting show the block as text. - Reading view renders the note as HTML (CommonMark plus tables, task lists, `==highlight==`, `#tags`, wikilinks, embeds, callouts `> [!note] Title`, and `%%comments%%` hidden). Clicking a task box toggles it in the file. - Editing commands: Ctrl/Cmd+B bold, Ctrl/Cmd+I italic, Ctrl/Cmd+K Markdown link, Ctrl/Cmd+Enter toggle checkbox, Ctrl/Cmd+F find in note, Undo/Redo. - Wrapping a selection: typing `[` while text is selected does not replace the text; the first `[` wraps it as `[text]` and keeps the text selected, and a second `[` makes it `[[text]]` (a link) with the text still selected. With no selection `[` is typed normally (with its closing bracket). - Autosave: changes are saved 800 ms after typing stops, on tab close, on switching notes and before the page unloads. The status bar shows "Saving…" then "Saved", "Offline – changes are kept here until you reconnect", or "Not saved – retrying". It also shows the word and character count of the note body (without properties). - Settings > Editor "Readable line length" limits the text width. - The same note open in two panes stays in step as you type in either. Accept when: the R4 test passes (including the properties block being hidden as soon as the note opens, checked in the R9 test). ### R5. Links and autocomplete - Typing `[[` opens a suggestion list of every note and attachment (fuzzy match on the name, then the path). Notes with aliases also list each alias; choosing one writes `[[Note|Alias]]`. If nothing matches exactly, the last entry is "Link to a new note" with what was typed. - `[[Note#` lists the headings of that note; `[[Note#^` lists its paragraphs and list items; choosing one that has no block id adds a random 6-character id (`^a1b2c3`) to the end of that line in the target note and writes `[[Note#^a1b2c3]]`. `[[#` lists headings of the current note. - The written link text follows Settings > Files & links "New link format": **Shortest path when possible** (just the name when no other file has that name, otherwise the full vault path), **Relative path to file**, or **Absolute path in vault**. "Use [[Wikilinks]]" off writes `[text](path%20with%20spaces.md)` instead. - Links are followed by clicking them in reading view, or Ctrl/Cmd+click (or click on the rendered text) in live preview; Ctrl/Cmd adds a new tab. A heading or block link scrolls to that place. Following an unresolved link creates the note (in the folder the link names, else the default location) and opens it. Unresolved links are drawn in a faded colour. - Link resolution and parsing follow `design.md` ("Link rules") exactly. Accept when: the R5 test and the unit tests "Parsing" and "Link resolution" pass. ### R6. Embeds - `![[Note]]` shows the whole note, `![[Note#Heading]]` that section (to the next heading of the same or higher level), `![[Note#^id]]` that block. Embedded notes render in a framed box with the source name; nesting stops at depth 3 and a note never embeds itself (cycle shows the link only). - `![[image.png]]` shows the image; `![[image.png|200]]` or `|200x100` sets the size. Audio and video show players; PDF shows in a frame. Missing targets show `"name" could not be found.` - Markdown image syntax to a vault file works the same. Accept when: the R6 test passes. ### R7. Keeping links correct on rename and move - When a file is renamed or moved (including a folder, which moves everything in it), every link in the vault that pointed at a moved file is rewritten so it still points at it, keeping its heading/block part, shown text and embed `!`. Wikilinks stay wikilinks and Markdown links stay Markdown links. - Rewritten links keep their form: `./`/`../` links stay relative to the linking note, links written with folders stay full vault paths, bare names use the vault's "New link format" (so they become a full path only if the bare name would now be ambiguous). - Links in a moved note that pointed at files that did not move are rewritten only if they would otherwise stop resolving to the same file. - Unresolved links are not touched. A move that makes an unresolved link resolve simply resolves it. - Settings > Files & links "Automatically update internal links" (on by default). When off, the app asks "Update links?" with the count of links and notes ("Update 3 links in 2 notes to point at the new name?") and Cancel leaves them as written. - The server does the rewrite inside the move request, as D1 batches of up to 400 statements (one batch for ordinary vaults), and returns how many notes and links changed. `dryRun` returns the counts without changing anything. Accept when: the R7 test and the unit tests "Rewriting" pass. ### R8. Backlinks and outgoing links - Right sidebar tab "Backlinks" for the active note: **Linked mentions** — each note that links here, with every linking line shown with the link highlighted, clicking a line opens that note at that line; **Unlinked mentions** — each place another note contains this note's name or one of its aliases as whole words (case-insensitive), outside links, tags, code and properties. Each unlinked mention has a "Link" button that turns that text into a link (`[[Name]]`, or `[[Name|text]]` when the text differs from the link text). - Toolbar: Collapse results, Show more context, sort (file name / modified time), and a filter box. - Tab "Outgoing links": links from the active note (resolved first, then unresolved shown faded with a "+" to create), and unlinked mentions of other notes' names in this note, each with a button that links it. - Both update as notes change. Accept when: the R8 test passes. ### R9. Properties - A YAML block between `---` lines at the very top of a note holds its properties. Types: Text, List, Number, Checkbox, Date, Date & time, and the fixed Tags type for `tags`. `aliases` and `cssclasses` are lists. A type is chosen once per vault per property name (stored on the server); when none is chosen it is inferred from the value. - In live preview and reading view the block is shown as a Properties panel (Settings > Editor "Properties in document": Visible / Hidden / Source) and never as text in live preview (R4). Each row: an icon for the type and the name (click for a menu: Rename…, change type, Remove) and an editor for the value (text input; chips with × and an "Add…" input for lists and tags; number input; checkbox; date and date-time inputs, with a button to open that day's daily note). "Add property" (also Ctrl/Cmd+; "Add file property") asks for a name. - Editing the panel rewrites only the YAML block, as one undoable change. Invalid YAML is never overwritten: the panel says "These properties are not valid YAML. Switch to source mode to fix them." - Right sidebar tab "All properties": every property name in the vault with its type and how many notes use it; clicking one searches `[name]`. - Links inside text properties (`"[[Note]]"`) count as links (R5, R8, R7). Accept when: the R9 test passes. ### R10. Tags - A tag is `#` followed by letters, digits, `_`, `-`, `/` or emoji, containing at least one non-digit, not inside code, links or URLs, and preceded by start of line, a space or `( , ;`. `/` makes nested tags (`#idea/later` is also under `#idea`). Tags in the `tags` property count too. Case-insensitive for matching; shown as first written. - Left sidebar tab "Tags": tag tree with counts (notes using the tag or any nested tag), sort by name or by count, nested or flat, expand/collapse all. Clicking a tag searches `tag:#name`; Ctrl/Cmd+click adds it to the current search. - Typing `#` in the editor suggests existing tags. Accept when: the R10 test passes. ### R11. Search - Left sidebar tab "Search" with a query box, Match case toggle, Explain search term option, Collapse results, Show more context, sort (file name A→Z / Z→A, modified new→old / old→new, created new→old / old→new), recent searches (last 10, on the device), "Copy search results" and "Bookmark this search". - Query language (full grammar in `design.md`, "Search"): words (all must appear, anywhere in the note or its path), `"exact phrase"`, `OR`, `-` to exclude, `( )` to group, `/regex/`, and the operators `file:` `path:` `content:` `tag:` `line:` `block:` `section:` `task:` `task-todo:` `task-done:` `match-case:` `ignore-case:`, and property filters `[name]`, `[name:value]`, `[name:null]`, `[name:>3]`, `[name:<3]`. An operator's value may be a group: `line:(a b)`. - Each result shows the note and its matching lines with the matches highlighted; clicking a line opens the note there. A query that does not parse shows the problem (for example "A bracket is not closed") instead of results. - Server side: FTS5 (trigram) narrows the candidates using the required words of 3+ characters; the exact rules are then applied in the Worker to the candidates. Results are capped at 500 files, 20 lines each. - Ctrl/Cmd+Shift+F opens search, filled with the editor selection if any. Accept when: the R11 test and the unit tests "Search" pass. ### R12. Quick switcher - Ctrl/Cmd+O. With an empty query it lists recently opened files, then the rest by modified time. Typing fuzzy-matches names, paths and aliases, best first (name matches before path matches; an alias match shows the alias with the note path under it). Matched letters are highlighted. - Enter opens; Ctrl/Cmd+Enter opens in a new tab; Shift+Enter creates a note with the typed name even if one matches; when nothing matches exactly the last entry is the typed text with "Enter to create". A name with `/` creates the folders. Up/Down (and Ctrl+N/P) move, Esc closes. A footer lists these keys. Accept when: the R12 test passes. ### R13. Command palette and hotkeys - Ctrl/Cmd+P lists every command available now (commands that need an open note are hidden when none is open), pinned commands first, then recently used, then A→Z, each with its hotkey. Fuzzy filter; Enter runs. - The command list and default hotkeys are in `design.md` ("Commands"). - Settings > Hotkeys: filter by name or key, "Set" records the next key combination (Esc cancels), a combination already in use is moved off the other command with a notice, "Reset" restores the default, and a pin button pins the command to the top of the palette. Hotkeys and pins are vault settings, so they follow the person between devices. - "Mod" means Cmd on macOS and Ctrl elsewhere. Hotkeys work everywhere except while a dialog is open; editor-only keys work only in the editor. Accept when: the R13 test passes. ### R14. Graph view - "Open graph view" (Ctrl/Cmd+G) opens the vault graph in a tab: one dot per note (and per attachment and tag when turned on), one line per link between two notes, unresolved link targets as faded dots. A dot grows with the number of notes linking to it. Laid out by a force simulation (d3-force), drawn on a ``. - Mouse: hover highlights the dot, its lines and neighbours and fades the rest and shows its name; click opens the note (Ctrl/Cmd+click: new tab); dragging a dot moves it; dragging the background pans; wheel zooms at the pointer; right-click a dot: Open in new tab, Open to the right. Keyboard with the canvas focused: arrows pan, `+`/`-` zoom. A hidden list of the shown notes (as buttons) gives screen readers the same choices. - Settings panel (gear button): **Filters** — search box (same language as R11) that limits which files are shown, Tags, Attachments, Existing files only, Orphans; **Groups** — rows of a search plus a colour, the first matching group colours a dot; **Display** — Arrows, Text fade threshold, Node size, Link thickness; **Forces** — Center, Repel, Link force, Link distance; "Restore defaults". Saved per vault on the device. A play button animates the notes appearing in order of creation. - Right sidebar tab "Local graph": the graph around the active note, with Depth 1–3 and Incoming / Outgoing links toggles; the active note is drawn in the accent colour. Accept when: the R14 test passes. ### R15. Daily notes - "Open today's daily note" (ribbon and palette) opens the note for today (server clock, browser time zone) at `/.md`, creating it from the template if missing. "Open previous daily note" and "Open next daily note" step through existing daily notes. - Settings > Daily notes: Date format (tokens in `design.md`, with a live example; `/` in the format makes folders), New file location, Template file location, Open daily note on startup. - Date properties (R9) have a button that opens that day's daily note. Accept when: the R15 test passes. ### R16. Templates - Settings > Templates: Template folder location, Date format, Time format. "Templates: Insert template" lists notes in the template folder and inserts the chosen one at the cursor, replacing `{{title}}` (note name), `{{date}}`, `{{time}}`, and `{{date:FORMAT}}` / `{{time:FORMAT}}`. If the template has properties they are merged into the note's: the note's existing values win, lists are combined without duplicates. "Insert current date" / "Insert current time" insert the formatted now. - Daily notes use the same variables. Accept when: the R16 test passes. ### R17. Tabs, splits and navigation - The main area holds tab groups arranged in nested horizontal/vertical splits with draggable dividers. Each tab has its own back/forward history (buttons and Ctrl/Cmd+Alt+←/→). Tabs can be dragged to reorder or onto another group; a context menu has Close, Close others, Pin/Unpin, Split right, Split down. Pinned tabs show no close button and following a link from a pinned tab opens a new tab. - Ctrl/Cmd+T new tab (an empty tab with: Create new note, Go to file, Open today's daily note, Close), Ctrl/Cmd+W close, Ctrl+Tab / Ctrl+Shift+Tab next/previous, Ctrl/Cmd+1…7 go to tab 1–7, Ctrl/Cmd+8 "Go to last tab". Opening a file replaces the active tab unless it is pinned. - Closing a group's last tab removes the group (the last group stays with an empty tab). The layout, open tabs, sidebar widths and open/closed states are saved per vault on the device and restored on load; tabs for files that no longer exist are dropped. - Left ribbon: toggle sidebar, quick switcher, graph, daily note, insert template, command palette, random note, theme, settings. Both sidebars can be resized and hidden (Ctrl/Cmd+\ and Ctrl/Cmd+Shift+\). Accept when: the R17 test passes. ### R18. Bookmarks - Left sidebar tab "Bookmarks": bookmarked files, folders, headings, blocks, searches, the graph, and groups that hold other bookmarks. Click opens (a search bookmark fills the search pane). Drag to reorder or into a group. Context menu: Edit title / Rename, Move out of group, Remove. "Bookmark the active tab" and Ctrl/Cmd+D bookmark what is open; "New bookmark group". - Bookmarks are stored on the server and follow file renames and moves. Accept when: the R18 test passes. ### R19. Attachments - Paste or drop images/files into the editor, or drop them on the explorer, to upload. Allowed: png, jpg/jpeg, gif, webp, svg, bmp, avif, mp3, wav, m4a, ogg, mp4, webm, mov, pdf; up to 20 MB each. Others get 415 "That kind of file cannot be added. Use an image, audio, video or PDF file." and too big gets 413. - Saved to the attachment location (Settings > Files & links: vault root, a folder — default `Attachments` —, the note's folder, or a subfolder of it). A pasted image is named `Pasted image YYYYMMDDHHmmss.png`. A taken name gets a number. The editor inserts an embed (`![[...]]` or Markdown image) at the drop point. - Bytes go to R2 under `v/`; `GET /api/vaults/:v/raw/:id` streams them with the right type, `Cache-Control: private, max-age=3600`, `X-Content-Type-Options: nosniff`, and for SVG a `Content-Security-Policy: sandbox` header. - Opening an attachment shows it in a file view (image, player, PDF frame) with Rename, Move, Delete and "Open in a new browser tab". Accept when: the R19 test passes. ### R20. Sync between devices - Every change bumps the vault's `seq` counter and stamps the file with it. Each open client polls `GET /changes?since=` every 5 s and when the window gets focus, and applies created, changed, moved and deleted files. An open note whose server text changed is reloaded in the editor when the person has no unsaved edits in it. - Saves send the version they were based on. If the server's version moved on, the server answers 409 with the current text and version. The client then does a three-way line merge (base = the last text it had from the server, mine, theirs). A clean merge is saved and shown in the editor. If the same lines changed on both sides the server text stays in the note and the local text is saved next to it as ` (conflict YYYYMMDDHHmm).md` (server clock, browser time zone), and a notice says exactly: `This note also changed on another device. Your version was saved as "".` — for example `... saved as "Reading list (conflict 202611150700).md".` (straight double quotes, the file name with `.md`). Nothing typed is ever silently lost. - Moves and deletes use the server's current state. A save to a note that was deleted elsewhere gets 404; the client saves its text as a new note at a free name in the same folder and says exactly: `This note was deleted on another device. Your text was saved as "".` (same quoting). Accept when: the R20 test and the unit tests "Merge" pass. ### R21. Appearance and settings - Light and dark themes (Settings > Appearance "Base color scheme": Adapt to system / Light / Dark; also a ribbon button) and font size, stored on the device and applied before first paint. Colours are CSS variables; the accent is `accent_color`. - Settings is a dialog with sections Account, People (only for the owner of an invite-only site, R24), Vaults, Editor, Files & links, Appearance, Hotkeys, Daily notes, Templates, Trash, About. Vault settings are saved on the server and apply on every device. - Settings > About shows the heading "About `app_name`", one line saying the app keeps Markdown notes, links and attachments on this site, and two rows: "Who can sign up" (the `access` choice: "Only me — sign-up closes after the first account", "Invite only — the owner invites people by email", or "Open — anyone can create an account") and "New accounts right now" ("Anyone can create an account", "Only people with an invite link", or "Nobody — sign-up is closed", after the `ALLOW_SIGNUP` override). Accept when: the R21 test passes. ### R22. Mobile layout - Under 768 px wide: no ribbon or tab bar; a top bar with the menu (left drawer), the note name, and the right drawer button; sidebars open as drawers over the note with a dimmed backdrop and start closed; a bottom bar with back, forward, quick switcher, new note, command palette and a tab-count button listing open tabs. Only the active pane of a split is shown. Opening a file closes the drawers. Settings shows its sections as a scrolling row. Accept when: the R22 test passes. ### R23. Safety and limits - All SQL uses bound parameters. Paths are normalised (no `..`, no empty segments, no leading `/`), at most 400 characters; names follow R3. - Request bodies over 25 MB (26,214,400 bytes) are refused (413 "That upload is too big"); note text over 1 MB is refused with 413 "Notes can be up to 1 MB"; attachments over 20 MB with 413 "Attachments can be up to 20 MB". - Rendered Markdown escapes raw HTML (HTML in notes is shown as text), and `javascript:`, `vbscript:`, `file:` and non-image `data:` URLs are never made into links. External links open in a new browser tab with `rel="noopener"`. - Unexpected errors return JSON `{ "error": "Something went wrong on our side. Try again." }` with 500 and are logged; no stack traces in responses. Accept when: the R23 test passes. ### R24. Who can sign up - The `access` input picks one of three modes. In every mode the first account created on the site becomes the **owner** (stored as a role on the account; the demo account from `seed_demo` is never the owner and does not count). Later accounts are **members**. Each person still has only their own vaults; nobody sees anyone else's notes. - `only_me` (default): once the owner exists, sign-up is closed. - `invite_only`: once the owner exists, a new account needs an invite link from the owner. - `open`: anyone can create an account at any time. - `GET /api/config` (no sign-in) returns `{ access, signup, firstAccount }` where `signup` is `open`, `invite` or `closed` right now. The sign-in page shows "New here? Create an account" only when `signup` is `open`. While no owner exists in `only_me` or `invite_only`, the sign-up page says "This is the first account. It becomes the owner of this site." - Closed: `/signup` shows "Sign-up is closed on this site." with a link to sign in instead of the form, and `POST /api/auth/signup` returns 403 "Sign-up is closed on this site". Existing accounts still sign in. - Invites (`invite_only`): Settings > People (owner only) says "This site is invite-only. Invite someone by email, then send them the link. Each link works once and expires after 7 days. The app does not send email." The owner types an email and presses "Invite"; the app shows "Invite link for :" with the link `/signup?invite=<64 hex characters>` and a "Copy link" button. Only the SHA-256 of the token is stored, so the link is shown once; inviting the same email again replaces the old link. Inviting an email that already has an account is refused with "That email already has an account". Lists: "Pending invites" (email, "expires ", Revoke) and "People with access" (name, email, Owner / Member / No access, and for members "Remove access" (asks first; signs them out everywhere and refuses their sign-in with 403 "This account no longer has access to this site"; their notes are kept) or "Give access back"). Non-owners get 403 "Only the owner can do that" from these APIs. - Opening a valid invite link shows the sign-up form with "You were invited as ." and the email filled in and read-only; the server also refuses another email ("Use the email address the invite was sent to"). An invite link that was used, revoked or is past its 7 days shows "This invite link is not valid or has expired. Ask the owner for a new one."; `/signup` with no link shows "You need an invite to create an account here. Ask the owner to invite you." The API answers 403 "You need an invite to create an account here" or "This invite link is not valid or has expired". A link is marked used in the same request that creates the account, so it works once. - Race safety: when only the owner may sign up, the insert of the new account itself checks that no owner exists, so two people signing up at once cannot both become the owner. - Override without a rebuild: the Worker var `ALLOW_SIGNUP` — empty (the default) follows `access`; `"0"` refuses every new account in every mode (invite links included, and the first account too); `"1"` lets anyone sign up in every mode (new accounts are members once an owner exists). - Cloudflare Access (`cloudflare_access`, default off): the app's own accounts always apply. When on, `wrangler.jsonc` has `"workers_dev": false` and `"preview_urls": false`, and the README's deploy steps include putting Cloudflare Access in front of the site: serve it on a custom domain (`routes` with `custom_domain: true`); in Zero Trust > Access controls > Applications add a **Self-hosted** application for that hostname; add an Allow policy that includes the allowed **emails**; keep **One-time PIN** as a login method so allowed people get a code by email; check in the dashboard that workers.dev and Preview URLs are disabled for the Worker; open the site in a private window to see the Access step before the app's sign-in. When off, the README still has these steps under "Optional: Cloudflare Access in front of the site". Accept when: the three R24 tests pass (only me: first account is owner, then closed in the page, the sign-in link and the API; invite only: invite, email lock, single use, revoke, 7-day expiry, member cannot manage, remove and give back access; open sign-up and the `ALLOW_SIGNUP` override), and the unit test "Access and cookies" passes. ## Tests - Unit (Vitest, `tests/`): the cases listed in `design.md` under "Unit tests" — parsing, link resolution, rewriting, search, merge, dates, templates, fuzzy match. - End to end (Playwright, `e2e/`): at least one test per requirement above, each titled with its own requirement id (`R2 …` for R2), against `wrangler dev` with a fresh local D1/R2 in `.e2e/`, `NOW` frozen at `2026-11-15T12:00:00.000Z`, `TEST_CLOCK=1`, `ALLOW_SIGNUP=1` (so tests can create accounts), browser zone `America/New_York`, the demo vault seeded. When `TEST_CLOCK` is `"1"`, the cookies `test_access` (a mode name) and `test_allow_signup` (`0`, `1`, or `auto` for "follow the mode") override `access` and `ALLOW_SIGNUP` per request, like `test_now`. The R24 tests live in `e2e/0-access.spec.ts` so they run first, on the empty database.