libre-study/CONVENTIONS.md

Libre Study Conventions

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

• This repo owns the application shell, interface, local storage, search behavior, import behavior, and desktop packaging.
• This repo does not own source Bible texts, commentaries, maps, lexicons, or study notes.
• Bible and study resources should enter the app through importable packages generated by libre-bible-data.
• Keep app code and resource data separate unless a tiny fallback seed is needed for development.

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.
• Phase completion means the version bump, code/docs changes, and validation result are committed locally and pushed to Gitea.
• The normal flow is local edit, local verify, local commit, push to Gitea, then publish or release from the pushed state.
• Do not publish release artifacts from a dirty worktree unless Jason explicitly asks for that exact operation.
• Keep source-control bookkeeping quiet unless Jason asks about it or a source-control problem affects the work.
• Use the actual project scripts instead of ad hoc equivalents.
• Use browser dev mode for fast visual iteration:

npm.cmd run dev:web

• Use Tauri dev mode when testing native behavior:

npm.cmd run dev:tauri

• 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.

Publishing Model

• Gitea is the Git host and backup/publishing surface, not the primary app UI.
• Public Gitea host: https://git.christit.com.
• Remote URL:

https://git.christit.com/libre-study/libre-study.git
git@git.christit.com:libre-study/libre-study.git

• Public download pages, catalogs, release notes, and package indexes should be generated from repo metadata where possible.
• Do not hand-maintain public catalog details that can be derived from committed manifests, package catalogs, tags, or releases.
• Release artifacts should be traceable to a pushed commit.
• Signed installers and updater metadata should only be produced from intentional release commits.
• Generated app metadata, package indexes, update manifests, and release notes should be regenerated by scripts rather than hand-corrected after the fact.

Backup Copies

• Source control is the main recovery layer, but local .old backups are still useful before large, risky, or release-bound edits.
• Put backups near the affected file or module, not in random temp locations.
• Prefer backup filenames with timestamp plus short reason, for example App.tsx.20260712-study-layout.old.
• Do not create .old backups for every tiny edit. Use them when rollback clarity is worth the extra file.

Changelogs

• Keep changelogs newest-first when changelogs are introduced.
• Use a ## Current section when helpful, followed by dated release sections.
• Keep entries concrete and operational: what changed, what behavior was preserved, and what was verified.
• Mark reconstructed history clearly if it is built from artifacts, old packages, or prior notes.

Data Boundary

• The app should import from libre-bible-data packages rather than scraping or downloading Bible sources directly.
• The app should prefer LibreBible machine catalogs over direct file guesses. Catalog paths may come from LIBREBIBLE_CATALOG_PATH, a sibling libre-bible-data checkout, or later a public ChristIT.com catalog.
• The local SQLite database is an app cache and user workspace, not the canonical source of public Bible data.
• User-created tags, highlights, notes, saved searches, layouts, and reading state belong to Libre Study.
• Translation text, Strong's links, study notes, commentaries, maps, and source metadata belong to libre-bible-data.

Product Direction

• 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

• Prefer TypeScript for UI and Rust/Tauri commands for native filesystem/database work.
• Keep UI components decoupled from Tauri invoke calls through a client layer so browser dev mode remains usable.
• 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.
• For normal HotView feature work, run the checks relevant to touched code, typically:

npm.cmd run lint
npx.cmd tsc --noEmit -p tsconfig.app.json

• For Vite config or Node-side tooling changes, also run:

npx.cmd tsc --noEmit -p tsconfig.node.json

• For Tauri/Rust changes, run:

cargo test

• Do not run builds as routine validation during HotView development unless explicitly requested.