Document Libre Study project state

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Changed the HotView HMR host from loopback-only `127.0.0.1` to the detected Tailscale IPv4 address, with a `VITE_HMR_HOST` override for other private intranet addresses.
+- Updated conventions and project-state notes before the planned consolidation phase.
 
 ## 0.1.34 - 2026-07-15
 

CONVENTIONS.md

@@ -1,6 +1,6 @@
 # Libre Study Conventions
 
-Libre Study is the desktop-first Bible study application. Its job is to provide a fast, local, searchable, taggable study workspace that can consume normalized Bible and study-resource packages from `libre-bible-data`.
+Libre Study is the platform-agnostic Bible study application. Its job is to provide a fast, searchable, taggable study workspace that can consume normalized Bible and study-resource packages from `libre-bible-data` while staying open-source and free to use where licensing permits.
 
 ## Repository Role
 
@@ -12,6 +12,9 @@ Libre Study is the desktop-first Bible study application. Its job is to provide
 ## Development Workflow
 
 - Local development happens in the workspace repo on drive `W:`.
+- During active product shaping, HotView/hot reload is the primary test loop. Do not spend cycles on web builds, local builds, installer builds, or hosted deployments unless Jason explicitly asks for a release/deploy pass.
+- HotView should stay reachable on the private Tailscale/local intranet, not the public internet. The normal connected-device URL is `http://desktop:5174/`.
+- Vite HMR should use the machine's Tailscale IPv4 address when available, with `VITE_HMR_HOST` as the private-address override.
 - The Christ Unscripted Gitea remote is the remote backup, collaboration, and publishing copy.
 - Do not treat work as durable until it is committed locally and pushed to Gitea.
 - Every named implementation phase should bump the app version and be recorded in Git both locally and remotely.
@@ -32,7 +35,7 @@ npm.cmd run dev:web
 npm.cmd run dev:tauri
 ```
 
-- Use packaged builds only when testing installers, app signing, updater behavior, or desktop release behavior.
+- Use packaged builds only when testing installers, app signing, updater behavior, desktop release behavior, or an explicitly requested release/deploy pass.
 - Browser dev mode may use mock/localStorage data. Tauri mode should use the native SQLite-backed commands.
 - If a command starts failing because of PowerShell, Bash, WSL, quoting, heredocs, pipes, regexes, `$` variables, or nested shell layers, stop retrying the same command shape. Move the logic into a script file or use argv-style execution.
 - Prefer PowerShell for normal Windows-local Node/Tauri work in this repo. Use WSL Bash only when a tool or script is genuinely Linux-oriented.
@@ -78,10 +81,11 @@ git@git.christit.com:libre-study/libre-study.git
 
 ## Product Direction
 
-- First target: Windows desktop.
-- First study source: KJV with Strong's-linked data.
-- Core experience: parallel reading, search, tags, notes, highlights, Strong's lookup, and saved study workspaces.
-- Later targets may include macOS, Linux, web/PWA, and mobile, but do not let those future targets compromise the desktop study workflow.
+- Product goal: a full-featured, open-source, free-to-use Bible study program where public resources are reusable and license-attributed.
+- Current lead lane: HotView/browser development on the private Tailscale/local intranet.
+- Platform target: one shared app core with adapters for browser/HotView, hosted web, Tauri desktop, and later PWA/mobile surfaces.
+- Core experience: page-first reading, search, tags, notes, highlights, Strong's lookup, maps, audio, exports, and saved study workspaces.
+- Desktop should remain account-optional/offline-capable when that lane resumes. Hosted web may add accounts, persistence, and collaboration after the single-user workflow is proven.
 
 ## Engineering Rules
 
@@ -90,11 +94,23 @@ git@git.christit.com:libre-study/libre-study.git
 - Do not hardcode Windows-only paths in app logic unless wrapped behind a platform adapter.
 - Treat installer output as a release artifact, not a normal development artifact.
 - Public release readiness is separate from internal app maturity. A build can be useful for local testing without being ready for public distribution.
-- Run at minimum:
+- For normal HotView feature work, run the checks relevant to touched code, typically:
 
 ```powershell
 npm.cmd run lint
-npm.cmd run build
+npx.cmd tsc --noEmit -p tsconfig.app.json
 ```
 
-before considering app changes complete.
+- For Vite config or Node-side tooling changes, also run:
+
+```powershell
+npx.cmd tsc --noEmit -p tsconfig.node.json
+```
+
+- For Tauri/Rust changes, run:
+
+```powershell
+cargo test
+```
+
+- Do not run builds as routine validation during HotView development unless explicitly requested.

ROADMAP.md

@@ -57,6 +57,8 @@ Work one phase at a time. A helper, spike, or supporting infrastructure task for
 - Phase 6: Notes, exports, and optional sync. Complete.
 - Phase 7: Study resource depth and polish. Complete.
 
+The next planned step is a consolidation pass that converts the completed foundation phases into durable product tracks. See [Project State - 2026-07-15](docs/project-state-2026-07-15.md).
+
 Supporting infrastructure already landed but not currently active as a phase: hosted web preview, hosted login, and deploy scripting. These remain parked until the user explicitly asks for a release/deploy pass.
 
 ## Phase 1: App Foundation And Bible Page Reader

docs/project-state-2026-07-15.md

@@ -0,0 +1,92 @@
+# Project State - 2026-07-15
+
+## Eventual Goal
+
+Libre Study should become a full-featured Bible study program built around open-source code and freely usable resources wherever licensing permits. It should stay platform-agnostic: one shared app core, with adapters for browser/HotView, hosted web, Tauri desktop, and later PWA/mobile surfaces.
+
+LibreBible remains the public resource package lane. Libre Study remains the study workspace and user-data lane.
+
+## Where We Started
+
+The project began as a local Bible reader and Tauri/React shell. The early questions were whether it could consume real Bible data, whether the app could stay independent from a single platform, whether HotView could be the primary development loop, and whether the study surface would be useful enough to guide the architecture.
+
+## Where We Are Now
+
+The project has moved from prototype into early product architecture.
+
+Working HotView behavior includes:
+
+- KJV and NET Bible text.
+- Strong's links and lexicon definitions.
+- Strong's pronunciation text when the package provides it.
+- KJV and NET footnotes and study notes.
+- Matthew Henry Concise commentary.
+- Easton and Smith dictionary entries.
+- OpenBible place context and UBS route labels.
+- KJV audio controls from the packaged Eliran Wong source.
+- Session-aware resource toggles.
+- Notes, timeline, imports, exports, and one-way Nextcloud WebDAV export.
+
+Architecture now includes:
+
+- `src/studyDataClient.ts` as the resource/query contract.
+- `src/studyClient.ts` as the browser/Tauri adapter router.
+- `src/workspace.ts` as the workspace/auth/session persistence contract.
+- Browser/HotView JSON package loading from sibling `W:\libre-bible-data`.
+- A Tauri/Rust/SQLite lane that exists but is not currently the lead development lane.
+- Hosted login/persistence infrastructure that exists but is parked until explicitly resumed.
+
+## Current Development Loop
+
+HotView is the active loop. Do not run web builds, local builds, installer builds, or hosted deployments unless explicitly requested.
+
+The private intranet/Tailscale target is:
+
+```text
+http://desktop:5174/
+```
+
+Vite HMR detects the machine's Tailscale IPv4 address when available. `VITE_HMR_HOST` can override that if a device needs a different private address. This is a private development path, not a public internet deployment.
+
+## What We Learned
+
+- Phase completion should mean: source updated, docs/changelog updated, validation run, committed, and pushed to Gitea.
+- Current repo state is more authoritative than memory or phase labels.
+- KeePass should own project credentials and operating notes where practical.
+- Passwords generated for project services should be around 16-20 characters, using uppercase, lowercase, and numbers, without special characters unless a service requires them.
+- Nextcloud export is one-way WebDAV export for now, not a primary database or full sync system.
+- Browser/HotView currently has the richest resource behavior; desktop hardening comes later.
+- Public resource data belongs to LibreBible. User workspace data belongs to Libre Study.
+- Do not show fake pronunciation playback controls until licensed pronunciation audio packages exist.
+- `desktop` resolves to multiple local addresses on this machine; the Tailscale IPv4 path is the reliable HMR target.
+
+## Where We Are Not Yet
+
+Libre Study is not yet a mature public Bible study application.
+
+Missing or immature areas include:
+
+- Cross-references.
+- More commentaries, lexicons, dictionaries, atlas images, and audio packages.
+- Licensed pronunciation audio packages.
+- Resource install/update/offline package management.
+- Mature hosted persistence and account lifecycle.
+- Desktop offline hardening and signed installers.
+- PWA/mobile adaptation.
+- Collaboration.
+- Public web release readiness: privacy, terms, license pages, abuse protection, backups, and monitoring.
+
+## Recommended Next Step
+
+The next phase should be consolidation, not another feature sprint.
+
+Consolidation should turn the completed Phase 1-7 foundation into durable product tracks:
+
+- Study experience.
+- Resource ecosystem.
+- Persistence and sync.
+- Platform adapters.
+- Public responsibility.
+- Collaboration.
+
+The goal is to preserve the platform-agnostic architecture before adding more features.