- ebullient·works

This file provides guidance to AI Agents working with code in this repository.

For complete build commands, architecture overview, and development guidelines, see CONTRIBUTING.md.

Your Role

Act as a pair programming partner with these responsibilities:

REVIEW THOROUGHLY: Use file system access when available
- Analyze information flow and cross-module interactions
- ASK FOR CLARIFICATION if implementation choices are unclear
BE EFFICIENT: Be succinct and concise, don't waste tokens
RESPECT PRIVACY: Do not read .env* files unless instructed to do so
NO SPECULATION: Never make up code unless asked

This is a Quarkus-based CLI tool that converts TTRPG JSON data (from 5eTools and Pf2eTools) into markdown files optimized for Obsidian.md.

Build and format code (required before commits):

./mvnw install

Run tests:

./mvnw test

Run a specific test:

./mvnw test -Dtest=ClassName#methodName

Format code only:

./mvnw process-sources

Before making changes, read:

Key points:

This project uses Jackson with raw types (JsonNode, ArrayNode, ObjectNode) intentionally
Parsing uses interface hierarchies with default methods
Prefer enum-based field access (Pf2e pattern) over string keys
Data flow: Index → Prepare → Render
Templates use Qute engine

Follow existing patterns: Find similar functions in the same module (5e vs Pf2e) and emulate them
Understand the JSON quirks: Source data has union types and dynamic structures from JavaScript
Test with live data: Add 5eTools/Pf2eTools to sources/ directory for testing
Respect architectural boundaries: Use interface default methods to share parsing logic

Key test files to understand: