docs: start USER-GUIDE.md — scaffold + Reading & Annotating

docs/USER-GUIDE.md

@@ -0,0 +1,140 @@
+# The songbird guide
+
+This guide picks up the moment songbird is running and you've signed in. (If you haven't gotten it
+running yet, the [README's "Get it running"](../README.md#get-it-running) walks you through that
+first — it takes about fifteen minutes and no coding.) From here on, we'll move through songbird the
+way you'll actually use it: reading, writing notes, and finding them again.
+
+## What's inside
+
+1. [Getting started in the app](#getting-started-in-the-app) — your account, the home page, picking
+   up where you left off
+2. [Reading](#reading) — moving around the Bible, switching translations, headings and notes, light
+   or dark
+3. [Annotating](#annotating) — writing a note, tagging it, linking a sermon to a passage
+4. [Study tools](#study-tools)
+5. [Finding things](#finding-things)
+6. [Exploring places and journeys](#exploring-places-and-journeys)
+7. [Comparing translations](#comparing-translations)
+8. [Your data](#your-data)
+
+<br>
+
+## Getting started in the app
+
+This is what you see every time you open songbird:
+
+![The songbird home page, with a verse-of-the-day card, a "pick up where you left off" link, a tally of your notes, and a list of recent notes](screenshots/welcome.png)
+
+It greets you by name and gives you a few ways back into Scripture.
+
+**Your account is yours.** The first person to sign up on a fresh songbird is the owner. If you share
+the computer, anyone else can make their own account too — and **each person's notes are completely
+private to them.** Nobody sees yours; you don't see theirs. Signing in is just the username and
+password you picked.
+
+**The verse of the day** sits at the top in your reading translation — a passage to greet you. Click
+**Open** to read it in full, or **Show another** if you'd like a different one.
+
+**Pick up where you left off.** Once you've done a little reading, a *"Continue in …"* link appears
+(here it's *Continue in Genesis 2*) and drops you back exactly where you were — same book, same
+chapter, same translation.
+
+Below that, a quiet tally of how many **notes**, **sermon notes**, and **tags** you've collected, and
+a list of your **recent notes** — each one a link straight back to the verse it sits on. The more you
+read and write, the more these fill in. This home page becomes *yours*.
+
+<br>
+
+## Reading
+
+Open a book and you're reading. Here's John chapter 3:
+
+![The reader showing John 3 with the "Jesus and Nicodemus" heading, and a note open in a panel on the right](screenshots/reader.png)
+
+That's the whole idea of songbird in one picture — Scripture on the left, and a note you wrote
+tucked into the margin on the right.
+
+**Getting around.** Up top, the **Book** and **Chapter** dropdowns take you anywhere; **← Prev** and
+**Next →** walk you one chapter at a time. In a hurry? The **Jump to…** box understands plain
+references — type something like `John 3` or `Gen 1:1` and press **Go**.
+
+**Switching translations.** A *translation* is one English wording of the Bible — songbird offers
+several (WEB, KJV, and more). Pick a different one from the **Translation** dropdown and the text
+re-renders in that wording. Here's the thing that makes songbird songbird: **your notes stay anchored
+to the verse, not the wording.** A note you wrote on John 3:16 shows up on John 3:16 in *every*
+translation. And if a note you wrote while reading one translation turns up while you're reading
+another, songbird marks it gently, so you always know where it came from.
+
+**Section headings.** Some translations include the little editor's headings that group a passage —
+like *Jesus and Nicodemus* over John 3 in the picture above. When a translation has them, they appear
+right in the text, no setting to flip.
+
+**Those small numbers in the verse.** A few Scripture engines also carry the translators' own
+footnotes. If you ever see **small raised numbers** sprinkled through the text, like this —
+
+![John 3 with small superscript numbers throughout the verses, the translators' study-note markers](screenshots/translator-notes.png)
+
+— those are translator's notes, and tapping one opens the translators' comment on that word or
+phrase. **The standard songbird setup includes none of these,** so most readers won't see them at all
+— there's nothing missing if your text is clean.
+
+**Light or dark.** The little sun/moon toggle in the top corner switches between a light theme and a
+dark one — easy on the eyes in a dim room — and songbird remembers which you prefer:
+
+![The reader in dark theme, showing John 3](screenshots/reader-dark.png)
+
+That's reading. Everything else in songbird hangs off of it.
+
+<br>
+
+## Annotating
+
+Reading is half of songbird. The other half is writing in the margins. **Click any verse number and
+a notepad opens beside it** — write, and it's saved the moment you do:
+
+![A note open beside John 1:1, with bold and italic text and a bulleted list, tagged "gospel" and "incarnation"](screenshots/note-editor.png)
+
+**Writing a note.** The notepad takes *rich text* — formatting like you'd use in a document. The
+**B**, **I**, and **Link** controls give you **bold**, *italics*, and links, and you can build
+bulleted lists, just like the note on John 1:1 above. Your notes are yours and private.
+
+**Tags.** A *tag* is a short label you stick on a note — *gospel*, *incarnation*, *comfort*, whatever
+helps. Add a few and later you can round up every note that shares one (that's coming up in
+[Finding things](#finding-things)).
+
+**Linking a sermon.** songbird can also pin a **sermon** — a talk you watched or preached — to the
+passage it's about. A small **▶** appears in the margin of those verses; tap it and the sermon's
+details open: its title, date, any tags, and a **link to watch**:
+
+![Psalm 23 with a ▶ marker on each verse, one open to show a sermon titled "The Lord Is My Shepherd" with its date, tags, and a watch link](screenshots/sermon.png)
+
+Because the note is anchored to the verse, that **▶** shows up no matter which translation you're
+reading. And when a passage has gathered **more than one** sermon, the marker shows a count — **▶ 2**
+— and tapping it opens a little chooser so you can pick which one to open:
+
+![Romans 8:28 with a "▶ 2" marker open to a "Sermons · 2" chooser listing two sermons](screenshots/sermon-chooser.png)
+
+That's the heart of songbird: read a verse, mark what speaks to you, and find it again later.
+
+<br>
+
+## Study tools
+
+*(Coming soon.)*
+
+## Finding things
+
+*(Coming soon.)*
+
+## Exploring places and journeys
+
+*(Coming soon.)*
+
+## Comparing translations
+
+*(Coming soon.)*
+
+## Your data
+
+*(Coming soon.)*

docs/dev-notes.md

@@ -4,6 +4,47 @@ A running log of per-slice decisions, gotchas, and how each slice was verified.
 
 ---
 
+## Docs Slice 2 — user guide: scaffold + Getting started / Reading / Annotating
+
+- **Date:** 2026-06-09
+- **Branch:** `slice/docs-2-user-guide`
+
+### Why
+With the screenshot set landed (Slice 1, PR #108), the actual guide can start. The README is a
+landing page (greet → install → feature list); this slice begins `docs/USER-GUIDE.md`, a single
+scrollable page with a table of contents that picks up *after* install and walks the new owner
+through using songbird, illustrated with the committed screenshots. Docs-only — no app/test/README
+change — so `make check` / `make check-frontend` are unaffected.
+
+### What shipped
+- New `docs/USER-GUIDE.md`: H1, a one-paragraph intro that assumes songbird is running + links back
+  to the README's "Get it running", and a full table of contents.
+- **Three sections written**, each opening with its screenshot then the explanation (show-the-win
+  voice rule): **Getting started** (`welcome.png` — account/privacy model, verse of the day, "pick up
+  where you left off", recent-notes); **Reading** (`reader.png`, `reader-dark.png`,
+  `translator-notes.png` — navigation, switching translations + the anchored-note invariant, section
+  headings, the conditional translator's notes, light/dark); **Annotating** (`note-editor.png`,
+  `sermon.png`, `sermon-chooser.png` — rich-text notes, tags, sermons + the multi-sermon chooser).
+- **Sections 4–8 are TOC stubs** (`## Heading` + *"(Coming soon.)"*) so the structure is whole and
+  every TOC link resolves now; Slices 3–4 fill them, Slice 5 trims the README.
+
+### Decisions / accuracy guards
+- **Image links are guide-relative** (`screenshots/<file>.png`), not repo-root like the README's
+  `docs/screenshots/…` — the guide sits in `docs/`.
+- **`welcome.png` is the older reused shot**, so the prose describes only its *content* (cards,
+  tally, recent notes), never its top-nav (it predates the Topics/Journeys nav items); navigation is
+  introduced from `reader.png` instead.
+- **Translator's notes are stated as conditional** — "the standard setup includes none, so most
+  readers won't see them" — and met gently ("if you ever see these small numbers…"), never via a
+  break-to-test "switch to NET to try it." Every claim was checked against the actual PNG.
+
+### Verified
+Image paths resolve from `docs/`, every TOC anchor matches a heading, prose re-checked against each
+referenced screenshot, read-back-as-the-reader pass on the three sections. `make check` (241 passed,
+4 deselected) + `make check-frontend` (221 passed, build clean) — unaffected (docs-only).
+
+---
+
 ## Docs Slice 1 — screenshot capture expansion (the user-guide's dependency)
 
 - **Date:** 2026-06-09