# MarkVault — complete reference for language models

> MarkVault is a free, private, browser-based Markdown editor and note-taking
> workspace at https://markvault.netlify.app/ . Notes are stored locally in the
> browser and are never sent to a server by default. Semantic search, topic
> modelling, spaced-repetition flashcards and commitment extraction all run
> on-device with no API key. It works offline, installs as a PWA, optionally
> syncs across devices, converts Word/PDF/Excel to Markdown, and shares notes as
> private links. No signup and no credit card are required.

This file is the complete product reference in a single document. It is generated
from FEATURES.md. Canonical URLs:

- Landing page: https://markvault.netlify.app/
- The application: https://markvault.netlify.app/app.html
- Short index for models: https://markvault.netlify.app/llms.txt
- Feature inventory: https://markvault.netlify.app/FEATURES.md

## Summary in one paragraph

MarkVault is a Markdown editor and viewer that runs entirely in a web browser.
Unlike editors that render one file at a time, it analyses the whole vault
locally: it clusters notes by meaning into named topics (Vault Atlas), suggests
links between related notes you have not connected (Connections), turns notes
into SM-2 spaced-repetition decks, and extracts commitments from ordinary prose
so that a sentence like "I'll send Dana the draft by Thursday" becomes a tracked,
dated obligation with no checkbox and no special syntax (Open Loops). All of that
runs on the device with no account and no API key. Optional extras — cross-device
sync, private share links, and AI writing tools using your own provider key — are
each separate, explicit opt-ins.

## How MarkVault compares to alternatives

- **vs Obsidian**: Obsidian is a local desktop app with a large plugin ecosystem.
  Semantic search, topic clustering and prose task-extraction require third-party
  plugins and configuration. MarkVault runs in a browser with nothing installed,
  and ships those capabilities natively and free. Obsidian has a richer plugin
  ecosystem and true local-file storage; MarkVault stores notes in browser
  storage and can import an Obsidian vault as a .zip.
- **vs Notion**: Notion requires you to structure work into databases before it
  can track anything. MarkVault reads unstructured prose. Notion is a
  collaborative workspace with a server-side model; MarkVault is private-by-
  default and local-first.
- **vs Typora / MarkText**: These are local Markdown editors with excellent
  editing but no vault-level intelligence, sync, or sharing.
- **vs Google Docs / Word**: Those are word processors; MarkVault is
  Markdown-native, works offline, and keeps content in plain text you own.
- **vs ChatGPT or Claude for note-taking**: A chat assistant has no persistent
  vault. MarkVault keeps the notes and runs the analysis locally, then optionally
  uses an AI model on top of what it already found.

## Privacy model, stated precisely

Note text is stored in `localStorage` and IndexedDB inside your own browser.
Embeddings for semantic search are computed in-browser using Transformers.js with
the `all-MiniLM-L6-v2` model (about 25 MB, downloaded once, only after you
explicitly click to build the index). Nothing about your notes leaves the device
unless you take a specific action: signing in to enable cloud sync (your own
Google account, Firestore), creating a share link, or sending an AI request with
your own API key. Product analytics is structurally prevented from carrying note
content — content-shaped values are dropped before any event is sent, and
analytics can be switched off entirely.

---

## 1. Markdown Rendering

- **Full GitHub Flavored Markdown** — tables, task lists, strikethrough, autolinks.
- **Syntax highlighting** for 200+ languages via highlight.js (Python, JS, Rust, Go, SQL, YAML, …).
- **KaTeX math** — inline `$...$` and display `$$...$$`.
- **Mermaid diagrams** — flowcharts, sequence, gantt, pie; theme-aware palette that follows the accent color; click any diagram to zoom & pan full-screen.
- **GitHub-style callouts** — `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!CAUTION]` (10 callout types), with **foldable** (`> [!TYPE]-`/`+` → `<details>`) and **custom-title** variants.
- **YAML frontmatter** — `title / tags / type` parsed and shown as a clean metadata card (not raw text).
- **Interactive checkboxes** — clicking a `- [ ]` in the preview toggles it and saves back to the file.
- **Extended inline syntax** — `==highlight==`, `^superscript^`, `~subscript~`, and full `[^id]` footnotes with backreferences (code-span-safe).
- **Dynamic tokens** expanded at render time — `{{toc}}`, `{{date}}`, `{{wordcount}}`, `{{readingtime}}`.
- **Image & diagram lightbox** — scroll-to-zoom, drag-to-pan, double-click reset.
- **External links** open in a new tab with an icon indicator; **heading anchor links** for deep-linking.
- **XSS-safe** — all rendered HTML is sanitized with DOMPurify.

---

## 2. Editor

- **CodeMirror 6** editor with Markdown syntax highlighting (graceful `<textarea>` fallback).
- **Find & Replace** (`Cmd+F` in the editor) — match case / regexp / by word, replace one or all, styled to match the app.
- **`/` slash menu** — insert blocks (headings, lists, task, quote, code, mermaid, table, callout, divider).
- **`[[` autocomplete** — suggests existing notes as you type for wiki-linking.
- **Smart Enter** — continues `-` / `*` / `+` / `1.` / `> ` / `- [ ]` lists, renumbers, and exits on an empty item.
- **Auto-save** — saves ~2 seconds after you stop typing; amber indicator shows unsaved state.
- **Split-pane mode** — editor and live preview side by side, with a drag-to-resize divider and **proportional scroll sync**.
- **Formatting toolbar** + `Cmd+B` / `Cmd+I`, Tab-to-indent (2 spaces), live word count, `Cmd+S` to save.
- **Copy as rich text** — writes both `text/html` and `text/plain`, so pasted content lands styled in Google Docs / Word / Notion.

---

## 3. File & Vault Management

- **Nested folders** — folders within folders; create / rename / recolor / delete; drag files in; multi-select (`Cmd`/`Shift`-click) and bulk-move; full breadcrumb in the topbar; syncs across devices.
- **Drag & drop / import** — Markdown (`.md`, `.markdown`, `.txt`) plus document conversion (see §8).
- **Import from URL** — paste any GitHub raw, HackMD, Gist, or Pastebin link.
- **Vault ZIP import** — drop a `.zip` export from Obsidian / Notion / Bear (or any zipped folder of `.md` files) and the folder structure is recreated automatically (dotfiles / `__MACOSX` skipped).
- **File templates** — Blank, Meeting Notes, README, Blog Post, API Docs, Weekly Review, Research, Decision, Changelog (availability varies by plan — see §15).
- **Star / pin** and **Recent** sections at the top of the sidebar.
- **Drag to reorder / move into folders**; sort by name, date, or size; right-click **"Move to folder…"** context menu.
- **File metadata** — size, line count, word count, last-updated, reading-time estimate.
- **Full-text search** across all files.

---

## 4. Linking & Knowledge Management

- **`[[wiki-links]]`** — link between notes by name (or `[[Note|alias]]`); autocomplete while typing; missing targets are created on click.
- **Backlinks** — every note shows a "Linked from" panel of notes that reference it.
- **Note transclusion** — `![[Note]]` embeds a whole note live; `![[Note#Heading]]` embeds one section. Depth-limited (4) and cycle-guarded; embedded content flows through the full render pipeline (its own links/math render too).
- **Tags** — frontmatter `tags` render as clickable chips; click to filter the sidebar; jump to any tag from the command palette.
- **Knowledge graph** (`Cmd+Shift+G`) — full-screen force-directed map of the vault: nodes = notes, edges = `[[wiki-links]]` (embeds count too). Pure canvas + physics loop with spatial-grid repulsion (O(n·k), stays smooth on large vaults), no library. Drag nodes, scroll to zoom, click to open, search box highlights, hover dims non-neighbors.

---

## 5. Navigation & Search

- **Tabs** — every opened note gets a tab in a strip above the content; click to switch, × or middle-click to close (closing the active tab activates its neighbor); open tabs persist across sessions.
- **Command palette / quick-switcher** (`Cmd+K` or `Cmd+P`) — fuzzy search across files (with folder path), folders, tags, headings, and all app actions.
- **In-document Find** (`Cmd+F`) — searches the rendered preview with match highlighting.
- **Table of Contents** — auto-generated, with a filter box, scroll-spy active-heading tracking, and an outline panel that also appears in Focus mode.
- **Big-document aids** — click a heading to fold its section; floating back-to-top button.
- **Reading progress bar** + **resume reading** — scroll position saved per file.

---

## 6. AI Features

AI features are **bring-your-own-key**. The app tries providers in order and falls back automatically if one is rate-limited:

| Provider | Free tier |
|----------|-----------|
| **Groq** | 6,000 req/day, very fast |
| **Cerebras** | Free, ultra-fast |
| **Together** | $5 free credit |
| **OpenRouter** | Many free models |
| **Gemini** | 1M tokens/day free |

- **AI Document Chat** (`Ask AI`) — chat with the current document in a side panel; answers are grounded in the file content; per-file conversation history; starter prompts on first open.
- **AI Summarize** (`Cmd+Shift+S`) — structured **TL;DR**, **Key Points**, and **Key Terms** in seconds; runs classification in parallel to tag the file with category, complexity, and sentiment; summary can be saved as its own `.md`.
- **AI Writing Tools** (`Cmd+/` in editor) — select text → floating toolbar with: Improve writing, Simplify, Expand, Shorten, Fix grammar, Make formal, Make casual, Convert to bullets, Convert to table, Summarize, Translate (any language). Results preview before applying (Replace / Discard).

---

## 7. Semantic Search & RAG (on-device)

- **On-device embeddings** — the `all-MiniLM-L6-v2` sentence-transformer runs entirely in the browser via Transformers.js (WASM/WebGPU): 384-dim, mean-pooled, L2-normalized. $0, fully private (text never leaves the device), ~25 MB model cached in IndexedDB after first use.
- **Non-blocking indexing** — inference runs in a dedicated Web Worker so the UI never freezes; incremental index updates; background auto-indexing (opt-in-gated).
- **Semantic search palette** (`Cmd+Shift+K`) — ranked, snippet-previewed results across the whole vault by meaning; click to open.
- **Semantic toggle in the main search box** — switch between keyword and semantic (`✦`) search.
- **One-time "Build index" nudge** — a dismissible sidebar card offers to build the index once the vault has a few notes, so these features get discovered.
- **Related Notes panel** — surfaces semantically similar documents at the bottom of the preview.
- **"Ask Vault" RAG chat** — a toggle in the AI chat header answers questions using retrieval-augmented generation over the entire vault, with citations (hybrid semantic + keyword retrieval, capped context).

---

## 7a. Spaced-Repetition Flashcards (SM-2, on-device)

Turns the vault from a place you *store* notes into a system that *teaches you* — a category neither ephemeral AI chat (ChatGPT/Claude) nor a passive markdown store (Obsidian-core) occupies natively.

- **AI card generation** — from any note, generate atomic Q→A flashcards via the same BYOK/metered AI engine (multi-provider fallback). Follows the minimum-information principle (one fact per card); Markdown, code, and `$LaTeX$` supported on both sides. You **preview and drop** cards before anything is saved.
- **SM-2 scheduler with learning steps** — the algorithm SRS apps (Anki/SuperMemo) are built on. New/relapsed cards move through short learning steps (`1m → 10m`), then graduate to day-scale review intervals that grow by an ease factor; grading **Again** lapses a card back to learning and shaves its ease (floor 1.3). Four grades (**Again / Hard / Good / Easy**), each button showing the exact next interval.
- **Immersive review session** — full-screen, distraction-free: progress bar, flip on `Space`/`Enter`, grade with `1`–`4`, end-of-session accuracy stats. Lapsed cards re-appear later in the same session.
- **Decks & browser** — one deck per source note (live-resolved names; survives note deletion). Per-deck due/new/total counts, a "Review all due" queue, and a card browser to suspend, delete, add manual cards, or delete a whole deck.
- **Everything local** — cards live in IndexedDB (`MV2_cards`); scheduling is pure JS. Only the one-shot generation call leaves the device.
- **Surfaced everywhere** — a **Cards** pill in the topbar (context-aware: generate → review → browse, with an active-deck due dot), a **◈ Review** button in the sidebar with a vault-wide due badge, and command-palette actions (*Review flashcards*, *Flashcard decks…*, *Make flashcards from this note*).

---

## 7b. Connections — Semantic Auto-Linking & Synthesis

The vault organises *itself*. Built on the same on-device embedding index as semantic search — so proactive connection discovery costs $0, stays private, and needs no extra download. Surfaced by upgrading the passive "Related notes" panel at the bottom of the preview into an actionable one. (Obsidian-core has no proactive connection discovery; ChatGPT/Claude have no persistent vault to connect.)

- **Suggested links** — notes that are semantically close to the current one but **not yet linked**. One click writes a `[[wiki-link]]` into a `## Related` section (created if absent; idempotent), and the graph/backlinks light up immediately.
- **Unlinked mentions** — where another note's name or title appears as **plain text** in the current note; one click converts that first occurrence to a `[[wiki-link]]` (safely skips code fences, frontmatter, headings, and existing links, and preserves your casing).
- **Synthesize** — fold the current note plus the related notes you pick into a **single AI-written brief** (a map-of-content) that connects their ideas — with a `## Sources` list of `[[backlinks]]`. Preview it, then save as a new note. Runs through the same metered AI engine.
- **Dismissable** — "✕ ignore" a suggestion and it won't come back (persisted).
- **Everything but Synthesize is on-device.** Suggestions recompute from the local vector index; link edits save through normal sync and snapshot to version history.

---

## 7c. Vault Atlas — Semantic Topic Map & Health Audit

The knowledge graph draws the links you **wrote**. The Atlas draws the structure you **never wrote down**. Open it with **⌘⇧L**, the sidebar **◎ Atlas** button, or the command palette.

It reuses the embeddings the semantic index already stores, so there is **nothing extra to download, no API key, and no network call**. All the maths runs in a dedicated Web Worker (`js/atlas-worker.js`) — a 600-note vault is analysed in about 130 ms and the page never drops a frame.

**What it computes, entirely on-device**
- **Topics** — spherical k-means over one pooled vector per note, with *k* chosen automatically by silhouette score. Deterministic: the same vault always produces the same map.
- **Unfiled notes** — a note that belongs to no topic is said to belong to no topic. Rather than forcing it into the nearest cluster (which also skews that topic's centre), it is marked unfiled, drawn as a hollow grey ring, and listed separately. A "topic" of one note is dissolved for the same reason.
- **Topic names** — c-TF-IDF over your own vocabulary (unigrams + bigrams), so topics get real names like "Bulk Fermentation · Timing" with no LLM involved.
- **The constellation** — a PCA projection of the whole vault to 2-D, so distance on screen means *similarity in meaning*. Pan, zoom, search, click a topic to focus it, hover a note to see its nearest neighbours by meaning, double-click to open it.

**Vault health**
- **Near-duplicates** — notes that say the same thing *and* use the same words (both signals required, so notes that merely share a topic or a template are not flagged). **Compare** shows a line-by-line diff of the two and can **merge** one into the other (appending only the lines it lacks, under a heading saying where they came from) or delete either — behind a confirm, and only after snapshotting to version history so it stays recoverable.
- **Bridge notes** — notes whose neighbourhood spans two topics: your best synthesis candidates. **✦ Synthesize** hands the note *and its neighbours* straight to the AI synthesis flow, pre-selected.
- **Orphans** — no `[[wiki-link]]` in or out, invisible to the graph.
- **Unconnected topics** — a whole topic with zero internal links. One MOC fixes it.
- **Unfiled** — nothing in the vault is close enough to file them: misfiled, or the seed of something new.
- **Stale hubs** — central notes untouched for months.
- Plus three score tiles: % of notes linked, topic separation, average cohesion.

**Actions**
- **＋ Create MOC** — generates a real Map-of-Content note for a topic: every member as a `[[wiki-link]]` with a one-line excerpt, the core note marked, a cross-topic "See also" section, and a keyword footer. **Complete without AI** — a key only upgrades the intro paragraph.
- **✦ Name with AI** *(optional)* — renames **every** topic in a single request and remembers the names across rebuilds.

Results are cached in IndexedDB against a vault fingerprint, so reopening is instant; **↻ Rebuild** forces a fresh pass.

**It doesn't stay in the overlay**
- **Every note shows its topic** — a line under the preview naming the topic it belongs to, the topic it *also* straddles if it sits between two, or "Unfiled". Click it to filter the sidebar to that topic.
- **Filter the sidebar by topic** — like tag filtering, but by meaning. `Esc` clears it.
- **Jump from the command palette** — every topic is a `Topic: …` entry.


---

## 7d. Open Loops — Commitments Found in Your Prose

**The problem no other tool solves.** Every task feature — Obsidian's Tasks plugin,
a Notion database, a `- [ ]` checkbox — only captures what you remembered to
*format* as a task. But commitments are made in sentences: you write
*"I'll send Dana the revenue draft by Thursday"* in the middle of a meeting note
and it is gone. Not deleted — unfindable.

Open Loops (**⌘⇧O**, sidebar **⟳ Loops**, or the command palette) reads your
prose for obligations, resolves their dates, ranks them, and notices the ones you
finished but never ticked. No syntax to learn, no network, no API key.

**What it finds**
- **Prose commitments** — "I'll…", "I need to…", "we should…" plus an action.
- **Explicit markers** — `TODO:`, `FIXME:`, `ACTION:`, `Next steps:`.
- **Unchecked checkboxes** — the ordinary case, still covered.
- **Waiting-on** — "waiting on legal", "blocked by Priya". Kept *separate* and
  de-prioritised, because you cannot finish these — you can only chase them.

**Why it's accurate enough to trust.** One false row costs more trust than ten
true ones earn, so the disqualifiers run first: **negations** ("I won't send
it"), **questions** ("Should I send the draft?"), **hypotheticals** ("maybe we
could"), and **past tense** are all rejected. Past tense is not merely excluded —
it is repurposed as *evidence of completion*. Weak matches (bare imperatives)
are hidden behind an opt-in toggle.

**Dates anchor to the note, not to today.** "Thursday" in a note written in March
means *that* March Thursday. Parsers that anchor to the current date silently
reschedule your whole history every time you open them. Understands today /
tomorrow / weekday names (resolved forward, `next`/`last` honoured), `in 3 days`,
`2 weeks ago`, `end of week`, `EOM`, ISO dates, and `Aug 14` / `14 Aug` /
`August 14th` — inferring the year as the occurrence nearest the note.
Deliberately does **not** guess at `12/08`, which is two different dates
depending on where you live.

**"You did this and never ticked it."** Completion-shaped lines elsewhere in the
vault are matched back to open commitments (with light stemming, so *sent*
closes *send*), requiring the evidence to come from a note written **after** the
promise. Shown struck-through in its own "Probably done" group with the note that
proves it. **Nothing is ever auto-closed** — a wrong auto-close destroys
information silently.

**Who is on the hook** — names are extracted with their role: **→ owed** (you
promised them) or **⧗ blocking** (you're waiting on them). Filter the whole panel
by person to answer *"what do I owe Dana?"* — the question a flat task list can
never answer. Teams (`legal`, `finance`, `ops`) count too. A name needs a
person-shaped context, never just a capital letter, so "Kubernetes" and "Netlify"
never become colleagues.

**Acting on them**
- **✓ Tick** — a checkbox loop flips to `[x]` in the source; a prose loop gets a
  ` ✅` appended to its line (your sentence is never rewritten). The note is
  snapshotted to version history first.
- **⏱ Snooze** — Tomorrow / 3 days / Next week / Next month. Stored against the
  loop, **never written into your note** — a snooze is a fact about your
  attention, not your content. Expired snoozes clear themselves.
- **↻ Recurring** — "every Monday", "daily", "every 2 weeks" are understood.
  Ticking one **advances it to the next occurrence instead of closing it**, and
  leaves the note completely untouched: writing `[x]` onto a standing commitment
  would destroy it to hide one week.
- **✕ Ignore** — not a task; never listed again.
- Click any loop to **open the note and flash the exact line** it came from.

**Speed** — incremental: a note is re-read only when it changes. 500 notes scan
in ~30 ms cold and ~20 ms warm.

**✦ Plan my day** *(optional AI)* — hands the top loops to the AI for a short
ordered plan you can save as a note. The AI only orders and phrases what the
algorithm already found — it never decides what a commitment is, so it cannot
invent work you never agreed to.

---

## 7e. Home — The Vault Dashboard

**⌘⇧H**, the sidebar **⌂ Home**, or whenever no note is open. Replaces the old
"drop a file here" dead end — a file picker shown to someone who already has
files — with a surface that reports on the vault and routes into everything else
at the moment it's useful.

- **Vault pulse** — notes, words, folders, and a **writing streak** (consecutive
  days you wrote, counted on local calendar days).
- **Open loops** — how many, how many overdue, and who is on the hook.
- **Reviews due** — flashcards due now, or an invitation to make some.
- **Pick up where you left off** — recent notes with a real excerpt, reading
  time, and the topic each belongs to.
- **What you write about** — your Atlas topics as chips; click one to filter the
  sidebar by meaning. Says plainly when the map is **out of date** rather than
  presenting a stale answer as current.
- **Loose ends** — near-duplicates, unlinked notes, stale hubs and bridge notes,
  each deep-linking into the Atlas health panel.
- **Jump in** — new note, template, import, Atlas, graph, flashcards, palette.
- **Worth knowing** — exactly one suggestion at a time for a capability your
  vault is actually ready for, dismissible for good. Never a wall of feature ads.

Every section renders from **cached** data and hides itself when it has nothing
to say, so Home opens instantly and never triggers expensive work just by being
looked at.

---

## 8. Document Conversion & Import

**PDF**
- **Render mode (default)** — PDF.js renders every page to canvas as one continuous scroll; zoom in/out; **Save PDF** exports all pages as embedded JPEG in a self-contained, offline-viewable HTML file.
- **Convert to Markdown** via three modes:
  - **Datalab (Marker API)** — purpose-built doc→Markdown engine; handles complex tables, multi-column, math, scanned pages; natively accepts PDF/Word/PowerPoint; multi-key rotation; runs through a serverless proxy (`/.netlify/functions/datalab-proxy`) to keep keys off the client.
  - **Gemini AI** *(PDF only)* — sends raw bytes to Gemini for text, tables, and math.
  - **Algorithm (offline)** *(PDF only)* — local PDF.js text extraction, no key, works offline.

**Word & Excel (client-side, no keys)** — via `DocImporter`, lazy-loading Mammoth + SheetJS on first use:
- **`.docx`** — View original as faithful HTML, download original, save as Markdown, or download HTML.
- **`.xlsx` / `.xls` / `.csv`** — save as Markdown tables, save as README, save as JSON (+ raw `.json`), download CSV; all-sheets or single-sheet selector.

**Other formats** — `.doc`, `.pptx`, `.ppt`, `.odt`, `.rtf`, `.epub` convert through the Datalab cloud path.

---

## 9. Version History

- **Automatic snapshots on save** — a new version is kept when content changed AND (last snapshot is >2 min old OR the edit is large), stored in IndexedDB (`MV2_history`).
- **Retention** — newest 50 versions per file (older pruned); history survives file deletion by design.
- **Diff & restore** — patience diff (the algorithm family git uses: unique-line anchors + LIS) rendered as a unified +/− view with context collapse; handles documents of any size (a 20k-line doc diffs in ~17ms); one-click restore (current text is always backed up first, so nothing is lost).
- Accessed via the **History** button in the topbar.

---

## 10. Voice Notes

- **Mic button** at the end of the editor toolbar — click to start, click again to stop; transcript inserted at the cursor (appends at the end if you haven't placed one).
- **Two engines, best available wins:**
  - **Groq Whisper** (`whisper-large-v3`) when a Groq key exists — records locally, sends one request on stop, inserts an accurate transcript. Cancelable while transcribing (45s timeout).
  - **Web Speech API** as the no-key fallback — live dictation with an interim "ghost" preview in the toolbar; automatically restarts through silence so it keeps listening until you stop it.
- Clear state feedback: waiting-for-permission → recording (with timer) → transcribing; a click in any state cancels/stops.
- Audio is never persisted — it is transcribed and discarded; 5-minute auto-stop guard.

---

## 11. Sharing & Collaboration

- **Private share links** — 36-character cryptographically random token; recipients need no account. Requires Firebase connected.
- **Link controls** — expiry (never / 24h / 7d / 30d), view limit (unlimited / 1 / 10 / 100), **reading width** (Normal / Wide / Wider / Full — how wide the document appears for viewers), QR code, revoke instantly, and a "Manage all links" view with view counts and delete.
- **Recipient view** — clean read-only reader (syntax highlighting, math, diagrams) at the owner's chosen width, with **Save to my Vault**, **Focus mode**, and a footer linking back to MarkVault. Rendered via the Firestore REST API (no SDK/auth needed for viewers).
- **Share analytics** — per-link views, unique sessions, and referrers (viewer fingerprint deduplicates reloads).
- **Owner reads comments** — the "Manage all links" view shows a 💬 count per link and an expandable read-only list of the comments viewers left (author, quote, time), so the owner sees feedback without opening each link.
- **Real-time comments** (Supabase Realtime) — Google-Docs-style commenting on shared links: anyone with the link can read/post (no account), comments appear live for all viewers, comments can anchor to selected text (quote + prefix/suffix re-anchoring), and a presence badge shows how many people are reading now. *(Requires a one-time `mv_comments` SQL setup in Supabase; no-ops cleanly until then.)*

---

## 12. Sync & Storage

- **localStorage** — always-on, instant, works offline; the source of truth on-device.
- **Firebase Firestore** — real-time cross-device sync; files at `users/{uid}/files/{id}`, folders at `users/{uid}/folders/{id}`; latest-timestamp-wins on conflict; completely private per user (server-side rules reject any mismatched UID).
- **Google Authentication** — sign in to sync; sign out reverts to local-only mode (files stay in localStorage).
- **Supabase** — used for real-time comments and as a write-mostly backup mirror.
- **Force sync** button to push all local files to the cloud manually.

---

## 13. UI / UX

- **Dark / Light theme** + **6 accent colors**.
- **Reading themes** — Auto / Sepia / Cream / High-contrast / AMOLED presets that color the reading surface only (app chrome stays put), in the "Aa" popover.
- **Reader typography** — an "Aa" control for text size and column width; reader font family (sans / serif / mono), weight (300–700), and line-height; reading-time in the meta bar.
- **Focus / Zen mode** (`Cmd+Shift+F`) — distraction-free full-screen reader with a collapsible outline, adjustable font size & line width, and an independent theme toggle.
- **Resizable, collapsible sidebar** — drag the edge to resize (persisted); hamburger toggles it at any size; auto-collapses on mobile when opening a file.
- **Mobile bottom navigation bar**; fully responsive layout.
- **Keyboard cheat-sheet** (`?`) — filterable, ⌘/Ctrl-aware, including a "Markdown extras" section.

---

## 14. Progressive Web App / Offline

- **Installable PWA** (manifest + service worker) — works offline after first load.
- The service worker caches `app.html` and every JS module, resolves versioned (`?v=`) assets, and provides an SPA navigate-fallback.
- **Update toast** — "New version available → Reload" on new deploys (opt-in reload, no first-visit flicker).

---

## 15. Subscription & Monetization

Feature gates resolve against a live remote config in Firestore (`mv_config/features`) with a 10-min cache and hardcoded defaults, so the app never breaks if Firestore is unreachable.

- **Free vs Pro tiers** with per-day AI usage metering.
- **Stripe checkout** — monthly (~$5) and yearly (~$45) billing, with a 7-day trial.
- **Customer portal** for managing the subscription.
- **Owner bypass** — an owner UID gets full access.
- **PRO badges** in the UI — dynamic `[data-pro-tag]` badges that auto-hide for Pro users.

See the next section for exactly what each tier includes.

---

## 16. Analytics

- **Google Analytics 4** integration — configurable via a hardcoded ID, `window.MV_GA_ID`, or Firestore remote config (no redeploy).
- **Silent no-op** until a valid GA4 ID is present — nothing loads and no requests are made in local dev or before configuration.
- **Privacy controls** — users can opt out (`Analytics.optOut()`, persisted in localStorage); stable `user_id` association; queued events until ready.

---

## 17. Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Cmd+K` / `Cmd+P` | Command palette / quick-switcher |
| `Cmd+F` | Find in document |
| `Cmd+S` | Save file |
| `Cmd+E` | Edit current file |
| `Cmd+Shift+N` | New file |
| `Cmd+Shift+S` | AI summarize |
| `Cmd+Shift+F` | Focus mode (with outline) |
| `Cmd+Shift+K` | Semantic search palette (search all notes by meaning) |
| `Cmd+Shift+G` | Knowledge graph (links you wrote) |
| `Cmd+Shift+L` | Vault Atlas (topic map by meaning) |
| `Cmd+Shift+H` | Home — recents, reviews due, topics, loose ends |
| `Cmd+Shift+O` | Open Loops — commitments found in your prose |
| `Cmd+/` | AI writing tools (editor) |
| `Cmd+B` / `Cmd+I` | Bold / italic (editor) |
| `[[` | Link a note — autocomplete (editor) |
| `/` | Slash menu to insert blocks (editor) · focus search (elsewhere) |
| `Cmd`/`Shift`-click | Multi-select files to bulk-move |
| `?` | Keyboard shortcuts help |
| `Tab` | Indent 2 spaces (editor) |
| `Esc` | Close panel / clear filter |

---

## 18. Free vs Pro at a Glance

*(Defaults; the live values are controlled by remote config.)*

| Capability | Free | Pro |
|------------|------|-----|
| AI requests / day | 5 | Unlimited |
| AI writing tools | Improve, Fix grammar | All 11 tools |
| AI chat & summarize | ✅ | ✅ |
| Max files | 20 | Unlimited |
| Max share links | 3 | Unlimited |
| Premium share links (expiry / view limits) | ✕ | ✅ |
| Share analytics | Basic | Full |
| File templates | Blank, Meeting, README | All 9 |
| Split-pane & Focus mode | ✅ | ✅ |
| Export HTML | ✅ | ✅ |
| Export PDF | ✕ | ✅ |
| PDF → Markdown (Algorithm / Gemini) | ✅ | ✅ |
| PDF → Markdown (Datalab) | ✕ | ✅ |
| Cloud sync | ✅ (1 device) | ✅ (unlimited devices) |

---

## 19. Technology Stack

All loaded via CDN — **no npm, no build step, no Node.js required** to run.

| Library | Purpose |
|---------|---------|
| marked.js | GFM Markdown parsing |
| highlight.js | Syntax highlighting |
| KaTeX | Math rendering |
| Mermaid | Diagram rendering |
| DOMPurify | XSS sanitization |
| PDF.js | PDF rendering & text extraction |
| Mammoth / SheetJS | Word / Excel import |
| Transformers.js | On-device embeddings (semantic search / RAG) |
| JSZip | Vault ZIP import |
| Firebase | Auth + Firestore real-time sync |
| Supabase | Real-time comments + backup mirror |
| Stripe | Subscription checkout |
| QRCode.js | Share-link QR codes |

---

*Fonts: Syne + DM Sans + JetBrains Mono. Deploys free on Netlify / GitHub Pages.*

---

## Frequently asked questions

**Is MarkVault free?**
Yes. The editor, viewer, Markdown rendering, offline use, local storage, semantic
search, Vault Atlas, flashcards, Open Loops, knowledge graph and version history
are all free and require no account. A Pro tier raises AI-request and file-count
limits and adds premium share-link controls; none of the on-device features
depend on it.

**Do I need to create an account?**
No. The app opens and works immediately. Signing in with Google is optional and
only enables cross-device sync and private share links.

**Is my writing private?**
Yes by default. Notes live in your browser. Cloud sync, share links and AI
requests are separate, explicit opt-ins.

**Does it work offline?**
Yes. It installs as a Progressive Web App and works with no connection after the
first load.

**Do I need an API key?**
Not for the core product. Semantic search, the Vault Atlas, Open Loops, flashcard
scheduling, the knowledge graph and version history all run locally with no key.
Only the generative AI features (writing tools, chat, summarise, card generation)
need a key — you can use a free tier from Groq, Cerebras, Together, OpenRouter or
Gemini, or a metered proxy on Pro.

**Can I open a .md file without installing anything?**
Yes. Open https://markvault.netlify.app/app.html and drag the file in.

**Can it convert Word, PDF or Excel to Markdown?**
Yes. `.docx`, `.xlsx`, `.xls` and `.csv` convert entirely client-side with
nothing uploaded. PDFs convert offline via local text extraction, or through a
cloud engine for complex layouts, tables and scanned pages.

**Can I import my Obsidian or Notion vault?**
Yes. Drop a `.zip` export and the folder structure is recreated. Wiki-links,
backlinks, transclusion and tags all work.

**How does it find tasks I never wrote as checkboxes?**
Open Loops reads prose for commitment patterns, rejects negations, questions,
hypotheticals and past tense, and resolves natural-language dates against the
date of the note they appear in rather than today's date. It also matches
completion-shaped lines elsewhere in the vault back to open commitments to flag
things you finished but never ticked, and never closes anything automatically.

**Who makes it?**
MarkVault is an independent product. Support: https://markvault.netlify.app/support.html