# MarkVault ◈ — Feature Overview

> A complete inventory of what MarkVault does **as of today**.
> MarkVault is a private, browser-based Markdown workspace with AI assistance,
> cross-device cloud sync, document conversion, semantic search, private sharing,
> and offline support — running entirely client-side with no build step.

**Architecture at a glance:** the marketing/landing page is `index.html` (served at `/`); the actual workspace is `app.html`. Everything runs in the browser — files live in `localStorage`, optionally mirrored to Firebase Firestore (primary sync) and Supabase (comments + backup). AI, embeddings, and document conversion all use the user's own keys or run on-device.

---

## Table of Contents

1. [Markdown Rendering](#1-markdown-rendering)
2. [Editor](#2-editor)
3. [File & Vault Management](#3-file--vault-management)
4. [Linking & Knowledge Management](#4-linking--knowledge-management)
5. [Navigation & Search](#5-navigation--search)
6. [AI Features](#6-ai-features)
7. [Semantic Search & RAG](#7-semantic-search--rag-on-device)
7a. [Spaced-Repetition Flashcards](#7a-spaced-repetition-flashcards-sm-2-on-device)
7b. [Connections — Auto-Linking & Synthesis](#7b-connections--semantic-auto-linking--synthesis)
7c. [Vault Atlas — Topic Map & Health](#7c-vault-atlas--semantic-topic-map--health-audit)
7d. [Open Loops — Commitments Found in Your Prose](#7d-open-loops--commitments-found-in-your-prose)
7e. [Home — The Vault Dashboard](#7e-home--the-vault-dashboard)
8. [Document Conversion & Import](#8-document-conversion--import)
9. [Version History](#9-version-history)
10. [Voice Notes](#10-voice-notes)
11. [Sharing & Collaboration](#11-sharing--collaboration)
12. [Sync & Storage](#12-sync--storage)
13. [UI / UX](#13-ui--ux)
14. [Progressive Web App / Offline](#14-progressive-web-app--offline)
15. [Subscription & Monetization](#15-subscription--monetization)
16. [Analytics](#16-analytics)
17. [Keyboard Shortcuts](#17-keyboard-shortcuts)
18. [Free vs Pro at a Glance](#18-free-vs-pro-at-a-glance)
19. [Technology Stack](#19-technology-stack)

---

## 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, to any depth. Every row carries
  **guide rails** back to its parent and the folder chain containing the open note
  is **lit**, so at depth three you can still see where you are. A `+` on any
  folder row nests a new one inside it; a small marker shows a folder has children
  without expanding it. Expanding staggers the children in and collapsing folds
  them back, so a mis-click reads as "it closed", not "my notes vanished". Full
  keyboard control (↑↓ to move, → to expand or step in, ← to collapse or step
  out), collapse-all / expand-all, drag a folder into another to re-parent it,
  create / rename / recolor / delete, multi-select (`Cmd`/`Shift`-click) and
  bulk-move, breadcrumbs in the topbar, and it all syncs across devices.
- **Foldable sidebar tools** — Flashcards / Loops / Atlas / Graph / Tables collapse
  into one row when you want the file tree to have the screen. Any waiting count
  moves up to the header, so folding can never hide something that needs you.
- **Files focus** (the `⤢` button above the file list) — one click and the whole
  navigation *condenses* into a single strip of icons, the promo cards step
  aside, and the file tree takes the sidebar. Nothing becomes unreachable: every
  destination is still one click away in the strip, and any waiting count follows
  it as a dot. Click again to go back.
- **Explorer** (`Cmd+Shift+B`) — the full-screen answer to "just show me
  everything". Folders open **sideways, one column per level**, so depth reads as
  distance instead of running out of indentation: at four levels deep every name
  is still full width and the path you took is still on screen behind you. Pick a
  note to preview it (title, location, word count, properties, an excerpt) without
  opening it, search the whole vault by name with each hit showing where it lives,
  add a folder at any level, or flip to a grid of every note in the branch when
  you care about the notes rather than the structure. Full keyboard control.
  Previews are **fully rendered** — tables, callouts, code, and maths look the
  way they will when you open the note, not like the file behind it.
- **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).
- **Daily notes** (`Cmd+Shift+D`) — today's note, created on demand in a `Daily`
  folder with a light frontmatter template (`title` / `type: daily` / `date`).
  Named ISO-style (`2026-08-01.md`) so they sort correctly and read the same in
  every locale, and dated from your **local** clock, not UTC. Yesterday's note is
  one command-palette entry away, and a `[[2026-07-15]]` wiki-link anywhere in the
  vault creates that day's note in the right folder.
- **Weekly & monthly rollups** — the **W** and **M** chips on the Today row (or the
  command palette) build a review of the period from what is already in your
  vault: what you ticked off, what is still open, the topics you wrote about, each
  day's headings, and the notes you created. **No AI is involved** — every line is
  something the vault already knew, so there is nothing to hallucinate. It is a
  normal `.md` note in a `Reviews` folder, and the generated part sits between
  markers so **"↻ Update" rebuilds it without touching a word you wrote in it**.
  ISO week numbering, from your local clock, correct across daylight-saving.
- **Tables** (`Cmd+Shift+E`) — a database view over the YAML frontmatter you already write. Columns are your own properties, rows are notes, and **editing a cell rewrites that note's frontmatter in place** (key order, quoting and body untouched; every edit snapshots to version history first). Filter by text or folder, sort by any column, and **group by any property to turn the table into a board**. There is no database behind it — a table is just a lens on `key: value` lines in your `.md` files, so it stays portable and deleting the view loses nothing.
- **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).

### Prompt-injection hardening

Retrieval means untrusted text — an imported page, a converted PDF, a pasted
email — reaches a model that is also holding your private notes. The 2026 attacks
on exactly this shape (EchoLeak, ForcedLeak) don't need the model to run a tool;
they only need it to *print an image URL* that a viewer then fetches. MarkVault
closes that structurally rather than asking you to be careful:

- **Nothing the model prints can phone home.** AI answers, share-link content, and
  notes that came from outside your vault never auto-load a remote image. You get
  a placeholder naming the host and a **Load image** button. Your own notes are
  untouched — a URL you typed yourself is not an exfiltration channel.
- **Retrieved notes are framed as data, not orders.** Excerpts are fenced and
  labelled, the text is escaped so it cannot break out of its frame, and the model
  is told explicitly to ignore any instruction found inside one and to never build
  a URL from excerpt text.
- **Every answer shows its sources — including when it has none.** If nothing
  matched, the answer says so rather than quietly looking vault-sourced. Notes
  containing instruction-shaped text are flagged in the source list.
- **Imported notes remember where they came from**, and you can trust one
  permanently with a single click. The marking lives in your preferences, never
  inside the note.

---

## 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.
- **Guided tour** — a spotlight walkthrough that rings each control and explains
  not just what it is but **why you would use it** (Loops, Atlas and Tables have
  no equivalent elsewhere, so the labels can't carry that on their own). Offered
  once after the welcome, skippable at any point, and always reachable from the
  **?** button in the sidebar footer or the command palette. It puts back
  anything it opened to show you a step.

---

## 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).
- **Share-sheet capture** — once installed, MarkVault registers with the OS as a share target, so a link, a selection or a note shared from any other app lands in your vault as an `Inbox.md` entry with its source and timestamp. Multiple shares queue up and append rather than scattering loose files, and a capture survives being shared before you've signed in. *(Android / ChromeOS — iOS does not support share targets.)*

---

## 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+D` | Today's daily note |
| `Cmd+Shift+E` | Tables — your notes by property |
| `Cmd+Shift+B` | Explorer — browse all files & folders |
| `?` | Shortcuts, and **Take the tour** |
| `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.*