AGENTS.md

Guidance for coding agents working in this repository.

Project intent

Build a reusable Android Java library that translates Markdown with Google ML Kit while preserving Markdown structure.

Primary roadmap source: current docs under docs/ (API, architecture, performance).

Repository layout

• library/ — core Android library module (main deliverable)
• sample/ — Android app used for manual verification
• docs/api.md — public API reference
• docs/architecture.md — AST/token translation architecture

Build, test, format

Use Gradle wrapper from repo root.

• Build sample app:
  • ./gradlew :sample:assembleDebug
• Run library unit tests:
  • ./gradlew :library:testDebugUnitTest
• Run formatting checks:
  • ./gradlew spotlessCheck
• Auto-format Java + XML:
  • ./gradlew spotlessApply

Formatting rules

• Java formatting is enforced by Spotless + googleJavaFormat (AOSP style).
• XML formatting is enforced by Spotless (eclipseWtp('xml')).
• Run spotlessApply before finalizing changes.

Implementation expectations

1. Keep library API small and stable.
2. Prefer AST/token-stream Markdown processing over regex-only logic.
3. Use regex fallback only for robustness/edge cases.
4. Preserve Markdown structure (headings, lists, quotes, code, links, spacing).
5. Keep Android/ML Kit integration separated from pure Java markdown logic where possible.

Language/SDK constraints

• Java 17
• Android minSdk 24
• compileSdk 34

Safety notes for changes

• Avoid introducing app-specific UI/business logic into library/.
• Keep sample UI behavior aligned with current UX requirements (toggle raw/rendered mode, model download/delete flow, etc.).
• Prefer additive/refactoring-safe changes with tests when modifying translation pipeline behavior.

Validation checklist before handoff

1. ./gradlew spotlessCheck
2. ./gradlew :library:testDebugUnitTest
3. ./gradlew :sample:assembleDebug

If device testing is requested:

• adb install -r sample/build/outputs/apk/debug/sample-debug.apk

Release process (JitPack)

Use this flow to publish a new version on JitPack.

1. Update version references in docs/sample as needed (for example, README.md and sample/build.gradle).
2. Run validation from repo root:
   • ./gradlew spotlessCheck
   • ./gradlew :library:testDebugUnitTest
   • ./gradlew :sample:assembleDebug
3. Ensure JitPack publishing config is present:
   • library/build.gradle includes id 'maven-publish'
   • release publication exists (from components.release, with sources jar)
   • jitpack.yml runs ./gradlew clean :library:publishReleasePublicationToMavenLocal
4. Commit release-related changes to main and push.
5. Create and push a new tag:
   • git tag -a X.Y.Z -m "Release X.Y.Z"
   • git push origin X.Y.Z
6. Trigger/verify JitPack build:
   • Open https://jitpack.io/#godsarmy/mlkit-markdown-translator-android
   • Select tag X.Y.Z and wait for success
   • Optional log URL: https://jitpack.io/com/github/godsarmy/mlkit-markdown-translator-android/X.Y.Z/build.log

Notes:

• Prefer creating a new tag (for example 0.8.2) instead of reusing/moving an existing tag.
• JitPack tags are effectively immutable for consumers; retagging can cause confusion/caching issues.