# Repository Guidelines

## Project Structure & Module Organization
This workspace contains two related repositories. `Xime/` is the Android input method built with Kotlin, Jetpack Compose, Gradle, CMake, and JNI. Its main app code lives in `Xime/app/src/main/java`, Android resources in `Xime/app/src/main/res`, bundled Rime/config assets in `Xime/app/src/main/assets`, JVM tests in `Xime/app/src/test`, and instrumented tests in `Xime/app/src/androidTest`. Shared plugin APIs are in `Xime/plugin-core`, sample plugins in `Xime/plugins`, and docs/screenshots in `Xime/docs`.

`winxime/` is the Windows/Rust TSF implementation. Rust crates live under `winxime/crates`, installer WiX files under `winxime/crates/winxime-server/wix`, runtime resources under `winxime/resources`, and vendored/native dependencies under `winxime/librime` and `winxime/rime-wubi`.

## Build, Test, and Development Commands
Run commands from the relevant subproject directory.

- Android build: `cd Xime; .\gradlew.bat assembleDebug --quiet` builds debug APKs.
- Android unit tests: `cd Xime; .\gradlew.bat :app:testDebugUnitTest` runs JVM tests.
- Android instrumented tests: `cd Xime; .\gradlew.bat :app:connectedDebugAndroidTest` requires a device or emulator.
- Docs: `cd Xime; pnpm docs:dev` serves VitePress docs locally.
- Windows build: `cd winxime; cargo build --quiet` validates the Rust workspace.
- Windows package: `cd winxime; .\msi-build.ps1` creates an MSI. `.\rebuild.ps1` rebuilds/registers locally; automated agents should not run it unless explicitly asked.

## Coding Style & Naming Conventions
Use Kotlin/JVM 17 and Rust 2021. Follow existing package namespaces such as `com.kingzcheung.xime.*` and Compose naming conventions: composables and screens use `PascalCase`, helpers/managers use descriptive `PascalCase` class names, and tests end in `Test`. Keep Gradle Kotlin DSL files as `*.gradle.kts`. In Rust, keep crate names kebab-case and modules snake_case. For `winxime`, do not introduce `unwrap()` or `expect()`.

## Testing Guidelines
Add or update tests when changing input logic, settings parsers, plugins, speech, association, or IPC behavior. Android unit tests use JUnit, Mockito, coroutines-test, and Compose test utilities; instrumented tests live in `androidTest`. Rust changes should at minimum pass `cargo build --quiet`; add crate-level tests where behavior is pure and deterministic.

## Commit & Pull Request Guidelines
Recent history uses Conventional Commit-style subjects such as `feat(settings): ...`, `docs(readme): ...`, and `chore(config): ...`; keep scopes specific. PRs should describe the user-visible change, list commands run, link related issues, and include screenshots or screen recordings for keyboard/settings UI changes.

## Security & Configuration Tips
Do not commit local signing material such as `Xime/app/keystore.properties`; use `keystore.properties.example` as the template. Treat `winxime/librime` as read-only unless the task explicitly targets native dependency updates. Automated agents should not commit changes unless requested.