# Research notes The builder does not need this file. It records where the design came from (provenance) and how the spec was checked; nothing in it is a requirement, and `spec.md`, `design.md` and `tasks.md` are complete without it. This spec describes a linked-notes app modelled on Obsidian, the Markdown knowledge-base app. Obsidian is proprietary. Everything here is written in our own words from its public help pages, its public plugin API typings and watching its public web pages. No Obsidian code, binaries, text, images, icons or branding were copied, and the built app must not use any of them (see "Names and words" in `spec.md`). The app bundle was not decompiled, disassembled or unpacked. ## Sources - **Help pages**: `help.obsidian.md` and its source repository `github.com/obsidianmd/obsidian-help` (commit `0a01159`, 2026-11-12), read for behaviour only. Pages read: internal links, aliases, embedding files, backlinks, outgoing links, search (operators, property filters, sorting, regular expressions, explaining a query, embedded queries), graph view (filters, groups, display, forces, local graph depth, time-lapse), tags and the tags view, quick switcher, command palette (pinned and recent commands), daily notes (date format, folder, template), templates (title/date/time variables, formats, merging properties), bookmarks (kinds and groups), properties (types, default `tags`/`aliases`/`cssclasses`, display modes), views and editing modes, managing notes (create, rename, delete), the file explorer, settings for new link format, automatic link updates and default locations, attachments, tabs and splits, and editing shortcuts. - **API typings**: `github.com/obsidianmd/obsidian-api` (MIT, commit `879c936`, 2026-11-10), read for the data shapes and documented rules: how a link path resolves to a file (`getFirstLinkpathDest`), how the shortest link text is chosen (the bare name when it is unique, otherwise the full path, per `fileToLinktext`), the resolved/unresolved link maps, and the cached metadata shapes for links, embeds, headings, blocks, tags and frontmatter links. - **Observed behaviour**: with REA (`rea-agents` 6.9.0 from npm, the official package), `rea capture-browser-scenario` of the public help site's "links" page in headless Chromium on 2026-11-16, with accessibility text and a screenshot. It showed the published-site rendering of wikilinks, a "links to this page" (backlinks) list and an interactive local graph, which informed the backlinks pane and local graph. Evidence files (kept by the spec author, not shipped): the scenario input, the Evidence JSON and its summary (`ev_ff3b64c7…` → summary view `ev_84ccadd8…`). ## Where this spec chooses differently - **A web app with a server.** The original is a desktop/mobile app over local files, with paid sync. Here the vault lives in Cloudflare D1 (notes, index) and R2 (attachments), and sync is the app's own polling API with versioned saves and a three-way merge; a clash is kept as a separate "conflict" note rather than lost. - **Link resolution is written down exactly.** The documented rule is "closest match"; this spec fixes the order (exact path, then the source note's folder, then fewest folders, shortest path, A→Z) so tests are stable. - **Rewritten links keep their form** (relative stays relative, full path stays full path), and links inside a moved note are rewritten only when they would otherwise break. - **Search** is evaluated in the Worker after FTS5 trigram narrowing, and supports the documented operators and property filters; embedded query blocks in notes are not included. - **Out of scope**: plugins, themes, canvas, database views, publishing, shared vaults, vault-wide block search, heading-rename updates, excluded files, file recovery snapshots. - **Own look**: own colours, icons, layout details and wording. - **Accounts and who can sign up.** The original has no server accounts. This spec adds accounts, an owner, a builder-chosen sign-up mode (`only_me` by default, `invite_only`, `open`), an `ALLOW_SIGNUP` override, and optional Cloudflare Access in front; these follow Cloudflare's documentation for Access self-hosted applications, not the original app. ## Checked by building it A build from these files (`linked-notes`) ran under `wrangler dev` with a local D1 and R2 (no Cloudflare account): 38 unit tests and 26 Playwright tests (one or more per requirement, each titled with its own requirement id) passed. `wrangler deploy --dry-run` bundled the Worker (about 70 KiB gzipped) without Node.js compatibility flags. A second, independent build made only from `spekkr.json`, `spec.md`, `design.md` and `tasks.md` also passed every requirement. Gaps found while building were fixed in the spec: rewritten links keeping their form, optimistic settings switches, conflict-copy timestamps on the app clock, saving text from a note deleted on another device, bookmarks following moves, property types for properties that have no value yet, drawers starting closed on phones, "Accept when" lines naming their own requirement, the properties block hidden from the moment a note opens, how `[` wraps a selection, the exact conflict notices, MB as 1,048,576 bytes, the `Secure` cookie exception for `localhost` and `127.0.0.1`, and Settings > About.