# AGENTS.md

Guidance for agentic coding tools working in `moasdawiki-app`.

## Project Snapshot

- Android app module: `:app`
- Language: Java 17 (no Kotlin sources currently)
- Build system: Gradle wrapper (`./gradlew`) + Android Gradle Plugin
- Main package: `net.moasdawiki.app`
- App depends on MoasdaWiki server module artifact: `net.moasdawiki:moasdawiki-server`

## Environment And Baseline

- Use the wrapper, not a globally installed Gradle: `./gradlew ...`
- Run commands from repository root.
- Keep changes scoped; do not refactor unrelated files.
- Preserve license headers in Java files.
- Prefer additive, minimal-risk edits.

## Build / Lint / Test Commands

### Common Lifecycle Commands

- Clean: `./gradlew clean`
- Build everything (assemble + checks): `./gradlew :app:build`
- Assemble debug APK: `./gradlew :app:assembleDebug`
- Assemble release APK: `./gradlew :app:assembleRelease`
- Install debug on connected device: `./gradlew :app:installDebug`

### Lint Commands

- Run lint (default variant): `./gradlew :app:lint`
- Run debug lint only: `./gradlew :app:lintDebug`
- Run release lint only: `./gradlew :app:lintRelease`
- Apply safe lint fixes: `./gradlew :app:lintFix`

### Unit Test Commands

- Run all unit tests: `./gradlew :app:test`
- Run debug unit tests: `./gradlew :app:testDebugUnitTest`
- Run release unit tests: `./gradlew :app:testReleaseUnitTest`

### Run A Single Unit Test (Important)

- Single test class:
  `./gradlew :app:testDebugUnitTest --tests "net.moasdawiki.app.YourTestClass"`
- Single test method:
  `./gradlew :app:testDebugUnitTest --tests "net.moasdawiki.app.YourTestClass.yourTestMethod"`
- Wildcard match:
  `./gradlew :app:testDebugUnitTest --tests "*YourTestClass*"`

Notes:

- Use fully-qualified class names for reliable filtering.
- If the filter reports no tests found, verify package + method names.
- Keep `Debug` test task unless you specifically need release behavior.

### Instrumentation Test Commands

- Run all connected instrumentation tests:
  `./gradlew :app:connectedDebugAndroidTest`
- Run one instrumentation class:
  `./gradlew :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=net.moasdawiki.app.YourAndroidTestClass`
- Run one instrumentation method:
  `./gradlew :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=net.moasdawiki.app.YourAndroidTestClass#yourTestMethod`

## High-Value Working Agreement

- Before editing, inspect nearby code and follow existing patterns.
- After editing, run the narrowest meaningful verification first.
- For behavior changes, prefer adding/updating tests when test infra exists.
- Do not introduce new build tools or formatting frameworks unless asked.

## Source Layout (Current)

- App code: `app/src/main/java/net/moasdawiki/app/`
- Resources: `app/src/main/res/`
- Manifest: `app/src/main/AndroidManifest.xml`
- Gradle module config: `app/build.gradle`
- Root build config: `build.gradle`, `settings.gradle`, `gradle.properties`

There are currently no `app/src/test` or `app/src/androidTest` files in this repository snapshot.

## Java Style Conventions To Follow

### Formatting

- 4-space indentation, no tabs.
- Opening brace on same line for classes/methods/control blocks.
- Keep methods reasonably focused; avoid large unrelated rewrites.
- Prefer one statement per line for readability.
- Preserve existing block comments and Javadoc style.

### Imports

- Use explicit imports; avoid wildcard imports.
- Group imports with blank lines by domain:
  1) `android.*`
  2) `androidx.*`
  3) `net.moasdawiki.*`
  4) `java.*`
- Keep import order stable and consistent within each group.

### Types And Nullability

- Use concrete types unless abstraction improves clarity.
- Follow existing nullability annotations (`@NonNull`, `@Nullable`).
- Annotate parameters/returns where null-safety is non-obvious.
- Prefer immutable locals/fields (`final`) where practical.
- Use boxed types only when null is a real state.

### Naming

- Classes: `PascalCase` (`MainActivity`, `SynchronizeWikiClient`).
- Methods/fields/local variables: `camelCase`.
- Constants: `UPPER_SNAKE_CASE`.
- Android log tags: short static constant named `TAG`.
- Preference keys/constants belong in `Constants`-style central locations.

### Control Flow And Readability

- Prefer early returns for invalid preconditions.
- Keep nesting shallow when possible.
- Extract helper methods for repeated logic.
- Use descriptive method names that reflect side effects.

### Error Handling And Logging

- Catch specific exceptions whenever practical.
- Log with Android `Log` at appropriate level (`d`, `i`, `w`, `e`).
- Include exception object when logging failures.
- Convert low-level failures into domain-friendly outcomes for callers.
- For user-visible failures, pair logs with UI feedback (`Toast`/status text).
- Avoid swallowing exceptions silently.

### Threading / Android Behavior

- Keep network and disk work off the UI thread.
- UI updates must run on UI thread (`runOnUiThread(...)` pattern).
- Continue using executor-based async style already present.
- Preserve lifecycle-safe behavior in `Activity`/`Fragment` methods.

## Testing Expectations For Agents

- If you change pure logic, add or update a unit test.
- If you change Android component behavior, prefer instrumentation tests when feasible.
- For low-risk refactors, run at least targeted lint + targeted tests.
- For broader edits, run `:app:lint` and `:app:testDebugUnitTest`.

## Dependency And Build File Edits

- Keep dependency changes minimal and justified.
- Match existing dependency declaration style in touched file.
- Do not upgrade AGP/Gradle/SDK versions unless explicitly requested.
- Call out deprecation warnings you encounter during Gradle runs.

## Commit And PR Hygiene (For Agents)

- Make small, reviewable commits with clear intent.
- In commit messages, explain why the change is needed.
- Include verification commands run and their outcome in PR notes.
- Do not include unrelated formatting churn.

## Cursor/Copilot Rule Ingestion

Checked in this repository:

- `.cursorrules`: not present
- `.cursor/rules/`: not present
- `.github/copilot-instructions.md`: not present

If these files are added later, agents should treat them as higher-priority repository instructions and merge them into this guidance.