1 files changed, 53 insertions, 0 deletions
diff --git a/desktop/modules/notes/README.md b/desktop/modules/notes/README.md
new file mode 100644
index 0000000..fa1a537
--- /dev/null
+++ b/desktop/modules/notes/README.md
@@ -0,0 +1,53 @@
+# notes
+
+`bash-notes` in the drawer: a tile with the note count, a list, and an editor
+that writes, edits and deletes notes in place. The store is `notes.sh`'s own,
+under its `BASEDIR` (default `~/.local/share/bash-notes`), so the page and the
+CLI work on the same notes: `db.json` is the index and `notes/` holds one file
+per note, named by its creation time in epoch seconds.
+
+- The list is newest first with a title search. A row opens the note.
+- The title lives only in `db.json` and the body only in the note's file, as
+  `notes.sh` keeps them.
+- The editor shows the title and the body, with a **Preview** switch that
+  renders the body as Markdown. Qt's Markdown is a subset: headings, emphasis,
+  lists, links, inline code and quotes render; tables and fenced-code
+  highlighting do not.
+- **Save** is two clicks: the first writes the note, the second reads
+  **Commit & push?** and pushes it. **Delete** is two clicks the same way.
+  With git off there is no second half, so Save writes and returns in one.
+- Leaving the editor with **Cancel**, the back arrow, Escape or a click
+  outside drops unsaved text. The save is the explicit act.
+- **Update list** runs `git pull` and stamps `git.lastpull`.
+
+Nothing pulls on open, so the list shows local state until **Update list** is
+pressed.
+
+**The page writes what `notes.sh` reads.** `id`, `title` and `file` are stored
+as strings, because `notes.sh` looks a note up with `select(.id == $i)` and
+would stop finding a note written with a numeric id. Only the `.notes` array is
+replaced; `params` and `git` carry through untouched.
+
+**A write is refused when `db.json` cannot be read as the index.** A
+`git pull --rebase --autostash` whose stash pop conflicts over a remote change
+leaves merge markers in `db.json` and still exits 0; reading that as "no notes"
+and writing it back would delete every title. The write reports
+`db.json could not be read; resolve it in <BASEDIR>` and leaves the file for
+git to resolve instead. A change made on two machines at once conflicts here
+for the same reason it conflicts for `notes.sh`: every machine appends to the
+one `db.json`.
+
+**Git order.** `notes.sh` pulls before it writes and commits after, and the
+page keeps that order: creating a note pulls first, then writes on what the
+pull brought in, and the commit and push are the second click. The one
+difference is `--autostash`, because a save here is two clicks and an
+unconfirmed save leaves `db.json` uncommitted where `notes.sh`'s write and
+commit are one invocation. `lastpull` is stamped after a pull that worked, not
+before it.
+
+`Notes.js` holds the parsing, sorting and transforms, tested with:
+
+    node desktop/modules/notes/test_notes.js
+
+Not here: opening a note in `$EDITOR`, backups (`--backup` / `--restore`),
+Markdown export, `--showconf` / `--userconf`, and pulling on open.