libre-study/CONVENTIONS.md

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.

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:.
• 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.
• 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, or desktop release behavior.
• 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.
• Planned remote URL pattern:

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

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

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.
• Run at minimum:

npm.cmd run lint
npm.cmd run build

before considering app changes complete.