scotttomaszewski_obsidian-disciples-journal/CLAUDE.md

CLAUDE.md

Guidance for Claude Code (and humans) working in this repo. Keep this file small — it is a map, not a manual. Detailed content lives in the docs it points to.

What this is

Disciples Journal is an Obsidian plugin that renders Bible references and passages inside notes (inline hover previews + full bible code blocks) and can download passages on demand from the ESV API. See README.md for the user-facing feature tour and manifest.json for plugin metadata.

Design ethos

Non-intrusive by default. People use this plugin during devotion, prayer, and small group. Features must never distract, frustrate, or shake the user out of an intimate time with God. Default to quiet: nothing new appears, moves, or interrupts until the user deliberately asks for it. No text shifting, no surprise popups, no persistent chrome. When in doubt, do less.

Where to look

• ARCHITECTURE.md — how the plugin is wired: services, components, data flow, and the lifecycle from main.ts to rendered verses. Read this before making structural changes.
• docs/ — focused references:
  • docs/index.md — table of contents for the docs folder
  • docs/gotchas.md — cross-cutting funky logic (listener lifecycle, pop-outs, cache, scroll)
  • docs/esv-api.md — ESV API integration, note storage, frontmatter
  • docs/reference-formats.md — supported reference syntax + parsing
  • docs/build-and-release.md — build, lint, and the just release flow
  • docs/testing.md — test harness, how to run tests, build/release gating
• FOLLOWUPS.md — small deferred findings captured during other tasks. Add an entry here instead of silently dropping out-of-scope work.
• ROADMAP.md — larger planned / in-flight efforts.
• CHANGELOG.md — released changes per version.
• docs/handoffs/ — session "you are here" state (owned by the creating-handoffs skill); empty until work is handed off mid-flight.

Conventions

• TypeScript, bundled with esbuild. Source lives in src/; main.ts is just the entry shim that re-exports src/core/DisciplesJournalPlugin.ts.
• This repo follows the obsidian-plugin-development skill (ESLint rules from eslint-plugin-obsidianmd). Invoke that skill when touching plugin APIs.
• Before committing: npm run build (runs tsc -noEmit + npm test + esbuild) and npx eslint . must both pass with zero errors/warnings. Tests live in test/ (npm test / devbox run test) — see docs/testing.md.
• main.js is a generated/bundled artifact — never edit it by hand.

Working agreements

Keep the docs true — they only save the next agent time if they're trusted. When you change the code, update the matching doc in the same change:

• Add/rename/remove a source file or service → update the module map in ARCHITECTURE.md.
• Change a build/lint/release command → update CLAUDE.md + docs/build-and-release.md.
• Add or change ESV API behavior or note storage → update docs/esv-api.md.
• 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.
• 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.