Doc cleanup

CHANGELOG.md

@@ -1,4 +1,8 @@
-# Changelog
+# Disciples Journal Releases
+
+New changes land under `## Unreleased`; at release time it is renamed by hand to the
+version tag (see [docs/build-and-release.md](docs/build-and-release.md)). Each `## `
+header text is **exactly** the release tag (no leading `v`).
 
 ## Unreleased
 

CLAUDE.md

@@ -52,5 +52,9 @@ change the code, update the matching doc in the same change:
 - **Add a new reference format or change parsing** → update `docs/reference-formats.md`.
 - **Introduce a workaround, magic number, or non-obvious behavior** → give it a home:
   a precise inline comment if local, a `docs/gotchas.md` entry if cross-cutting.
-- **Defer something out of scope** → add a `FOLLOWUPS.md` entry; promote it to
-  `ROADMAP.md` (and a plan doc) if it grows into a real effort.
+- **Ship a user-facing change** → add a bullet under `## Unreleased` in `CHANGELOG.md`.
+- **Hit a small in-scope tangent** (worth fixing, but it'd derail the current task) →
+  add a numbered `## N.` section to `FOLLOWUPS.md`, and clear it before the next feature.
+- **Plan a new feature or larger effort** → add a numbered `## N.` section to
+  `ROADMAP.md` (and a plan doc once work starts). `FOLLOWUPS.md` and `ROADMAP.md` serve
+  different lifespans — don't fold one into the other.

FOLLOWUPS.md

@@ -1,22 +1,28 @@
-# Workspace Follow-Ups
+# Follow-ups
 
-Lightweight tracking for tasks identified during other work that weren't tackled in the original scope. These are intentionally deferred — captured here so they don't get lost.
+In-scope tangents found while working — important to fix, but they'd derail the task
+at hand. Add a numbered `## N.` section below instead of chasing them now, and
+**clear these before starting a new feature.** New features and larger efforts go in
+[ROADMAP.md](ROADMAP.md), not here.
 
-Add new entries at the top. Remove entries when done (commit message can reference them).
+Mark a finished item with a `**Status:** done` line rather than deleting it; completed
+items get pruned and the rest renumbered on a periodic cleanup pass. Each entry
+carries the repo's standard fields (Identified / What / Why / Context / Effort), where
+Effort is sized XS (<1 h) · S (1–4 h) · M (1 day) · L (multi-day).
 
-## Entry format
+<!-- Template — copy for each item, numbering sequentially:
+## N. Short title
+**Status:** open
+- **Identified:** YYYY-MM-DD, the work it came up in.
+- **What:** brief description of the change.
+- **Why:** the motivation / what value it adds.
+- **Context:** file paths, gotchas, anything that saves the next person grep time.
+- **Effort:** XS | S | M | L
+-->
 
-Each entry should include:
+## 1. Finish pop-out window styling
 
-- **Identified:** YYYY-MM-DD and the work it came up in
-- **What:** brief description of the change
-- **Why:** the motivation / what value it adds
-- **Context:** background, file paths, gotchas, anything that would save the next person 10 minutes of grepping
-- **Effort:** rough sizing — XS (<1 h), S (1–4 h), M (1 day), L (multi-day)
-
----
-
-## Finish pop-out window styling
+**Status:** open
 
 - **Identified:** 2026-05-31, funky-logic sweep.
 - **What:** Styles aren't fully ported into freshly created pop-out windows.

ROADMAP.md

@@ -1,20 +1,85 @@
 # Roadmap
 
-Larger planned or in-flight efforts. For small deferred findings see
+New features and larger planned / in-flight efforts, tracked as numbered `## N.`
+sections. For small in-scope tangents to clear before the next feature see
 [FOLLOWUPS.md](FOLLOWUPS.md); for released history see [CHANGELOG.md](CHANGELOG.md).
 
 > Entries below are **observations** about likely directions, inferred from the
-> code — not committed plans. Promote one to a real plan/spec doc (and a
-> `## Status` section) when work actually starts.
+> code — not committed plans. When work actually starts, promote the item to a real
+> plan/spec doc and add a `## Status` line here. Mark a shipped item
+> `**Status:** done`; prune and renumber on a periodic cleanup pass.
 
-## No efforts currently in flight.
+Each item carries a **Lens** (User-facing / Technical health / Growth & ecosystem)
+and an **Effort** tag: XS (<1 h) · S (1–4 h) · M (1 day) · L (multi-day).
 
-## Observed future directions
+## 1. Multiple Bible versions
 
-- **Multiple Bible versions.** The storage path scheme is already
+- **Lens:** User-facing · **Effort:** L
+- The storage path scheme is already
   `<bibleContentVaultPath>/<preferredBibleVersion>/...` and settings expose a
   "preferred version", but `BookNames`, `ESVApiService`, and rendering assume ESV
-  end-to-end. Generalizing would mean a version-agnostic content-source seam.
-- **A test harness.** There are no automated tests. `BibleReference.parse` (pure,
-  pattern-heavy, highest-risk logic) is the natural first target. See
-  [FOLLOWUPS.md](FOLLOWUPS.md).
+  end-to-end. The headline feature; needs a version-agnostic content-source seam.
+
+## 2. Bundled offline public-domain version (KJV/WEB)
+
+- **Lens:** User-facing · **Effort:** M
+- Today the plugin is inert without an ESV API token. Shipping a public-domain
+  translation bundled in the plugin means it works on install with zero setup — a big
+  onboarding win and a natural first consumer of the multi-version seam (#1).
+
+## 3. Copy / export passage with attribution
+
+- **Lens:** User-facing · **Effort:** S
+- A "copy passage" action that emits clean markdown/text and auto-appends the required
+  ESV copyright line. Serves the journaling use case and respects the copyright
+  obligation noted in `README.md`.
+
+## 4. Touch / mobile interaction
+
+- **Lens:** User-facing · **Effort:** M
+- `isDesktopOnly` is `false`, but the core interaction is hover-to-preview, which
+  doesn't exist on touch. Define a tap/long-press affordance so the plugin is actually
+  usable on mobile.
+
+## 5. Reading plans / daily reading
+
+- **Lens:** User-facing · **Effort:** M
+- A code block or command that surfaces a day's passage from a plan (e.g. M'Cheyne,
+  chronological). Leans on existing passage rendering; turns the plugin from a
+  reference tool into a daily-habit tool.
+
+## 6. Expand the test harness
+
+- **Lens:** Technical health · **Effort:** M
+- `BibleReference.parse` is covered; extend to `BookNames` normalization, `BibleFiles`
+  path/filename logic, and the `BibleContentService` resolution funnel
+  (cache → note → API). The highest-leverage safety net before the multi-version
+  refactor (#1). See [docs/testing.md](docs/testing.md).
+
+## 7. Multi-source content seam
+
+- **Lens:** Technical health · **Effort:** L
+- Decouple "where content comes from" from ESV specifically (bible-api.com, local
+  USFM/USX import, etc.). Pairs with multiple versions (#1) but is the *source* axis
+  rather than the *version* axis; enables offline import workflows.
+
+## 8. Rendering robustness: finish pop-out styling + large-passage perf
+
+- **Lens:** Technical health · **Effort:** M
+- Promote the pop-out styling gap tracked in [FOLLOWUPS.md](FOLLOWUPS.md), and address
+  rendering very long passages (lazy/virtualized render, cache eviction) so whole-book
+  blocks don't jank.
+
+## 9. Community plugin store submission
+
+- **Lens:** Growth & ecosystem · **Effort:** S–M
+- The repo already follows `eslint-plugin-obsidianmd` and gates on lint/tests. Getting
+  listed in Obsidian's community catalog is the single biggest distribution lever and
+  mostly a compliance/review task.
+
+## 10. Clickable cross-references & footnotes
+
+- **Lens:** Growth & ecosystem · **Effort:** M
+- The ESV HTML already carries footnotes and cross-references (rendered today as static
+  text). Making cross-refs clickable to open/preview the target passage turns rendered
+  passages into a navigable study surface.

docs/build-and-release.md

@@ -31,7 +31,11 @@ The repo follows `eslint-plugin-obsidianmd` (see `eslint.config.mjs`) and the
 
 ## Releasing
 
-Releases go through the `justfile` (`just release <version>`), which:
+**Before releasing**, rename the `## Unreleased` header in [../CHANGELOG.md](../CHANGELOG.md)
+to the version tag — the `justfile` does **not** touch the changelog (it creates the
+GitHub release with empty notes), so this promotion is a manual step.
+
+Releases then go through the `justfile` (`just release <version>`), which:
 
 1. Refuses to run if `git status` is not clean.
 2. Runs `npm test` — a failing test aborts the release before any files are mutated.
@@ -39,7 +43,7 @@ Releases go through the `justfile` (`just release <version>`), which:
 5. Builds with `npm run build-no-check`.
 6. Commits (`Prepares for release '<version>'`) and pushes.
 7. Creates a GitHub release with `gh`, uploading `main.js`, `manifest.json`, and
-   `styles.css` as assets.
+   `styles.css` as assets (release notes are left empty — the changelog is the record).
 
 ### gh token note