diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 3927767..5a37142 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -213,12 +213,79 @@ and never locked inside one machine. ## Exploring places and journeys -*(Coming soon.)* +The "Places in this chapter" peek from [Study tools](#study-tools) has a fuller home here. songbird +gives you two ways to wander the world the Bible happens in: **every place** named in it, and a set +of **journeys** you can trace stop by stop. + +**Every place, in one list.** Open **Places** up top for the *gazetteer* — a browsable index of every +location Scripture names: + +![The Places page, a searchable, filterable list of locations with their type, coordinates, and a confidence label](screenshots/places-gazetteer.png) + +That's more than thirteen hundred of them. **Search by name**, or narrow the list with the **Status** +filter (how sure we are of where it sat) and the **Type** filter (river, settlement, region, +mountain…). Each row tells you what kind of place it is, its coordinates, and — honestly — how +confident that location is. + +**Open a place to see it up close.** Tap any name for its own page: what it is, its modern name if it +has one, the honest confidence in its location, and **every verse that mentions it** — each one a +jump straight back into the reader: + +![A single place's page — Rameses — showing its details, the verses that name it, and a "Journeys through here" section](screenshots/place-detail.png) + +And notice the **"Journeys through here"** section at the bottom — Rameses, it turns out, is a stop on +*The Exodus from Egypt*. That's the second way to explore. + +**Follow a journey.** Open **Journeys** for the curated set — the Exodus, Paul's missionary travels, +his voyage to Rome — each listed with its passage, rough dating, and how many stops it has: + +![The Journeys page, listing five curated journeys with their passages, dating, and stop counts](screenshots/journeys-list.png) + +Open one and songbird draws its **route on a map with numbered stops**, followed by a **Stops** list +in order — each stop tied to the passage it comes from, ready to jump to: + +![The Exodus journey, its route drawn on a map of Sinai with numbered stops and a prominent note above the map](screenshots/journey-detail.png) + +**One honest caveat, shown right above the map.** A journey like the Exodus is **one scholarly +reconstruction, not a GPS track.** The route, the Red Sea crossing point, and many wilderness stops +are genuinely uncertain — some carry low or medium confidence, and songbird says so plainly rather +than pretending otherwise. Competing routes and fine-grained dating aren't drawn at all. And a stop +whose location nobody knows is still **listed in order — just marked "Location unknown" and left off +the map** rather than pinned to a guess. You're seeing a careful best-reading of the text, with its +seams left honest. + +
## Comparing translations -*(Coming soon.)* +Sometimes the clearest way to understand a verse is to set wordings side by side. Open **Compare**: + +![The Compare page showing John 3 in three translations — NET, AKJV, and ASV — in parallel columns, lined up verse for verse](screenshots/compare.png) + +You can read **up to three translations at once**, each in its own column, **lined up verse for +verse** — so verse 3 in one column sits right beside verse 3 in the others. Pick the translation at +the top of each column; the Book, Chapter, and **← Prev / Next →** controls work just like the +reader. Any **notes you've written show up in the column they belong to** (here they're read-only — +Compare is for reading across, not editing). + +It's the quickest cure for a puzzling phrase: a line that reads stiffly in one translation often comes +clear the moment you see how another renders it. + +
## Your data -*(Coming soon.)* +That's the whole of songbird. A few things worth keeping in mind as you go. + +**Your notes are yours.** Each account's notes are private to the person who wrote them — nobody else +who uses this songbird can see yours (see [Getting started](#getting-started-in-the-app)). + +**They're portable.** You're never locked in: the **Export** and **Import** buttons in Browse notes +save all your notes and sermons to a single file and load them on another computer — the walkthrough +is back in [Finding things](#finding-things). + +**Read however suits the room.** The light/dark toggle is always in the top corner, and songbird +remembers your choice (more in [Reading](#reading)). + +That's everything. Open a chapter, click a verse, and write the first thing that speaks to you — the +rest of songbird is just here to help you find it again. 🕊️ diff --git a/docs/dev-notes.md b/docs/dev-notes.md index 1ff3e57..74949cb 100644 --- a/docs/dev-notes.md +++ b/docs/dev-notes.md @@ -4,6 +4,48 @@ A running log of per-slice decisions, gotchas, and how each slice was verified. --- +## Docs Slice 4 — user guide: Exploring + Comparing + Your data (content complete) + +- **Date:** 2026-06-09 +- **Branch:** `slice/docs-4-user-guide` + +### Why +Fills the last three stubs of `docs/USER-GUIDE.md` (Slices 2–3, PRs #109/#110) — **Exploring places +and journeys**, **Comparing translations**, **Your data** — completing the guide's content. After +this slice **no `(Coming soon.)` stub remains**. README trim is the final slice (Slice 5). Docs-only +— `make check` / `make check-frontend` unaffected. + +### What shipped +- **Exploring** — Places gazetteer (`places-gazetteer.png`: search + Status/Type filters, 1,340 + locations) → place detail (`place-detail.png`: Rameses, modern name, verses, and the **"Journeys + through here"** block bridging into Journeys) → Journeys list (`journeys-list.png`) → journey detail + (`journey-detail.png`: route map + numbered stops + ordered Stops list). Honors the forward-link + Slice 3's Study-tools section made to this section. +- **Comparing** — up to three translations in parallel columns, lined up verse for verse, per-column + notes read-only (`compare.png`). +- **Your data** — short closer; recaps privacy / Export-Import / theme with back-links to Getting + started, Finding things, Reading (no new screenshots), and a final wrap beat. + +### Decisions / accuracy guards (verified against the components + PNGs) +- **Journeys honesty is the section's spine**, mirroring the in-app amber callout + (`JourneyDetailView.tsx:66–71`): one scholarly **reconstruction**, not a GPS track; uncertain + crossing/stations shown at low/medium confidence; competing routes & fine dating not modeled; and + **unlocated stops listed in order but marked "Location unknown" and left off the map, not pinned** + (`JourneyDetailView.tsx:84–123`). Same honest posture as the earlier conditional features. +- **Compare stated from source** — `MAX_COLUMNS = 3`, read-only annotation overlays scope-filtered + per column (`CompareView.tsx:13–20`); per-column notes described as behavior, not claimed visible + in the shot. +- **`## Your data` heading kept** (not renamed to the brief's "& settings") so the existing TOC + anchor `#your-data` keeps resolving. + +### Verified +`grep "Coming soon"` → 0; all 5 newly-referenced images resolve from `docs/`; every internal anchor +referenced (`#study-tools`, `#getting-started-in-the-app`, `#finding-things`, `#reading`) matches a +heading; TOC unchanged. Read-back-as-the-reader + accuracy pass on all three sections. `make check` +(241 passed, 4 deselected) + `make check-frontend` (221 passed, build clean) — unaffected (docs-only). + +--- + ## Docs Slice 3 — user guide: Study tools + Finding things - **Date:** 2026-06-09