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

```powershell
npm.cmd run dev:web
```

- Use Tauri dev mode when testing native behavior:

```powershell
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`.
- Remote URL:

```text
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:

```powershell
npm.cmd run lint
npm.cmd run build
```

before considering app changes complete.