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.

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
• 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 + esbuild) and npx eslint . must both pass with zero errors/warnings.
• 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.
• Defer something out of scope → add a FOLLOWUPS.md entry; promote it to ROADMAP.md (and a plan doc) if it grows into a real effort.