cleanup docs for agents (#448)

Author: 0xh3rman

AGENTS.md

@@ -53,7 +53,11 @@ This is a crypto wallet. Treat security-sensitive changes as high risk by defaul
 
 ## Task Completion
 
-During active implementation, rebase conflict resolution, or compile-fix loops, prefer targeted build/test commands and defer broad lint/format runs until the change is ready to commit. Do not skip the required lint/format checks silently before final handoff; run them then, or report the exact reason they are still pending.
+For documentation-only changes, do not run mobile/core build and test suites unless the docs change also modifies executable scripts, generated inputs, localization inputs, CI configuration, build configuration, or release/security procedures. Verify docs-only changes with lightweight checks such as `git diff --check`, link/path inspection, and a quick read-through of the edited files.
+
+During active implementation, rebase conflict resolution, or compile-fix loops, prefer targeted build/test commands and defer broad verification until the change is ready to commit. Do not run full platform builds, full test suites, broad lint, or format after every small edit unless the risk of the change requires it. Do not skip required lint/format checks silently before final handoff; run them in the final verification batch, or report the exact reason they are still pending.
+
+Run final verification as a batch after you believe no more code edits are needed. If formatting, localization, generation, or a compile fix changes source after that batch starts, rerun the affected targeted checks before handoff.
 
 Before finishing a task:
 1. Build the affected platform(s)

android/AGENTS.md

@@ -31,13 +31,10 @@ Read `core/AGENTS.md` when the task touches `core/`, generated models, JNI bindi
 ## Task Completion
 
 Before finishing an Android task:
-1. Build the affected variant or module
-2. Run the relevant Gradle tests
-3. Run the relevant lint and formatting tasks when Kotlin or resources changed
+1. Use [Quality Checks](../skills/quality-checks.md) to choose targeted vs full verification
+2. Run at least one real Gradle verification command for the touched codepath
+3. If `core/` changed, regenerate shared artifacts and verify Android still builds
 4. Clean imports and avoid unnecessary comments
-5. If `core/` changed, regenerate shared artifacts and verify Android still builds
-6. In tests, prefer shared `:gemcore` fixtures with sensible defaults over inline full-field mock construction
+5. In tests, prefer shared `:gemcore` fixtures with sensible defaults over inline full-field mock construction
 
-Add or update tests only for high-impact behavior where a compact test materially reduces risk; skip trivial logic and purely visual Compose polish unless coverage is explicitly requested or already cheap to extend.
-
-Do not finish an Android task without running at least one real Gradle verification command for the touched codepath. `git diff --check`, code inspection, or reasoning are not enough. If Gradle is blocked by unrelated repo failures, report the exact command and the blocking error instead of claiming the change was verified.
+For UI changes, smoke the changed flow on an emulator or device when the flow is reachable. `git diff --check`, code inspection, or reasoning are not enough. If Gradle is blocked by unrelated repo failures, report the exact command and blocking error instead of claiming the change was verified.

android/skills/development-commands.md

@@ -32,6 +32,25 @@ For release builds, read `release-and-verification.md`.
 
 From the repo root, use `just start-emulator`, then `just run-android` as the default Android run flow.
 
+## Compose Iteration
+
+For presentation-only Compose work, build the owning module first and avoid repeating full app builds for each visual adjustment:
+
+```bash
+./gradlew :features:asset:presents:assembleDebug
+./gradlew :features:settings:settings:presents:assembleDebug
+./gradlew :ui:assembleDebug
+```
+
+For ViewModel or display-model behavior, pair the module build with the narrowest matching unit test:
+
+```bash
+./gradlew :features:asset:viewmodels:testDebugUnitTest
+./gradlew :features:wallets:presents:testDebugUnitTest
+```
+
+Use `./gradlew assembleGoogleDebug` when the change touches app composition, navigation wiring, flavor-specific code, generated bindings, or code that cannot be validated by a module build.
+
 ## Test and Quality Commands
 
 ```bash

android/skills/testing.md

@@ -7,6 +7,7 @@
   - `just test` or `./gradlew testGoogleDebugUnitTest` — Google Debug unit tests
   - `just test-integration` or `./gradlew connectedGoogleDebugAndroidTest` — instrumented tests (requires emulator)
   - `./gradlew :app:testGoogleDebugUnitTest` — app module only
+  - `./gradlew :<module>:testDebugUnitTest` — one feature or shared module
 - Run the narrowest relevant target while iterating, then finish with broader validation
 
 ## Test Structure

ios/AGENTS.md

@@ -25,12 +25,9 @@ Read `core/AGENTS.md` when the task touches `core/`, generated bindings, or file
 ## Task Completion
 
 Before finishing an iOS task:
-1. Run `just build`
-2. Run the relevant tests with `just test ...` for unit coverage or `just test-integration` / `just test-ui` for iOS integration coverage
-3. Run `just lint` and `just format` when Swift code changed
-4. If generated files or `core/` changed, run the required generation step and verify iOS still builds
-5. Keep imports clean and remove dead code
+1. Use [Quality Checks](../skills/quality-checks.md) to choose targeted vs full verification
+2. Run at least one real verification command for the touched codepath
+3. If generated files or `core/` changed, run the required generation step and verify iOS still builds
+4. Keep imports clean and remove dead code
 
-Add or update tests only for high-impact behavior where a compact test materially reduces risk; skip trivial logic and purely visual SwiftUI polish unless coverage is explicitly requested or already cheap to extend.
-
-Do not finish an iOS task without running at least one real verification command for the touched codepath. `swift build` succeeding is not the same as the feature working — for UI changes, exercise the flow on a simulator or device. If verification is blocked by unrelated repo state, report the exact command and the blocking failure instead of claiming the change was verified.
+`swift build` succeeding is not the same as the feature working. For UI changes, exercise the changed flow on a simulator or device when the flow is reachable. If verification is blocked by unrelated repo state, report the exact command and blocking failure instead of claiming the change was verified.

ios/skills/development-commands.md

@@ -8,8 +8,10 @@ Use the iOS `justfile` commands by default.
 just bootstrap              # first-time setup
 just clean                  # clean DerivedData and build artifacts
 just build                  # build the app
-just build-package Primitives
+just build-for-testing      # build once for repeated test runs
+just build-package Primitives # build one Swift package/scheme
 just test                   # run unit test plans
+just test-without-building  # re-run tests after build-for-testing
 just test AssetsTests       # run a specific test target
 just test-integration       # run iOS integration/UI tests
 just test-ui                # run iOS integration/UI tests
@@ -29,6 +31,32 @@ just localize               # update localization files
 
 From the repo root, use `just generate-stone` and `just run-ios` as the default Gemstone/iOS flow. The optional `GemStone` Xcode scheme combines cached Gemstone generation with the normal app build.
 
+## SwiftUI Iteration
+
+For presentation-only SwiftUI work, build the owning package first and avoid repeating full app builds for each visual adjustment:
+
+```bash
+just build-package Assets
+just build-package Components
+just build-package PrimitivesComponents
+```
+
+For ViewModel or display-model behavior, pair the package build with the narrowest matching test target:
+
+```bash
+just test AssetsTests
+just test LockManagerTests
+```
+
+For repeated test debugging, build once and re-run without rebuilding:
+
+```bash
+just build-for-testing
+just test-without-building
+```
+
+Use `just build` when the change touches app composition, navigation wiring, generated bindings, or code that cannot be validated by a package build.
+
 ## Additional Utilities
 
 ```bash

ios/skills/testing.md

@@ -6,6 +6,7 @@
 - Default commands:
   - `just test`
   - `just test <TARGET>`
+  - `just build-for-testing` followed by `just test-without-building` for repeated test-debug loops
   - `just test-integration` or `just test-ui` for the iOS integration suite
 - Run the narrowest relevant target while iterating, then finish with the appropriate broader validation
 

skills/new-feature-workflow.md

@@ -31,10 +31,11 @@ Read `ios/AGENTS.md`. Work in `ios/`.
 
 1. Add Swift UI, ViewModel, or service code that consumes the new types
 2. If extending generated models, add Swift extensions in separate files — never edit generated files
-3. Build and test:
+3. Iterate with targeted package/test commands first, then run broader validation:
    ```bash
+   cd ios && just build-package <PACKAGE>
+   cd ios && just test <TARGET>
    cd ios && just build
-   cd ios && just test
    cd ios && just lint
    ```
 
@@ -44,10 +45,11 @@ Read `android/AGENTS.md`. Work in `android/`.
 
 1. Add Kotlin UI (Compose), ViewModel, or repository code that consumes the new types
 2. Wire dependencies through Hilt modules
-3. Build and test:
+3. Iterate with targeted module/test commands first, then run broader validation:
    ```bash
+   cd android && ./gradlew :<module>:assembleDebug
+   cd android && ./gradlew :<module>:testDebugUnitTest
    cd android && ./gradlew assembleGoogleDebug
-   cd android && ./gradlew test
    cd android && ./gradlew lint
    ```
 

skills/quality-checks.md

@@ -1,46 +1,49 @@
 # Quality Checks
 
-Run the checks that match the area you touched.
+Run the checks that match the area you touched. Use the narrowest meaningful command while iterating, then finish with the broader validation required by the risk of the change.
 
-## Verification Matrix
+For SwiftUI and Compose work, pure presentation changes should not spend most of the loop in full app builds.
+
+## Iteration Matrix
+
+| Change Type | Inner Loop Checks |
+|-------------|-------------------|
+| iOS presentation-only SwiftUI | `cd ios && just build-package <PACKAGE>` |
+| iOS ViewModel, formatter, validation, or display-model behavior | `cd ios && just build-package <PACKAGE>`<br>`cd ios && just test <TARGET>` when a targeted test exists or is added |
+| Android presentation-only Compose or resource change | `cd android && ./gradlew :<module>:assembleDebug` |
+| Android ViewModel, formatter, validation, or display-model behavior | `cd android && ./gradlew :<module>:assembleDebug`<br>`cd android && ./gradlew :<module>:testDebugUnitTest` when a targeted test exists or is added |
+| Core-only Rust change with no mobile API impact | `cd core && just test <CRATE>` |
+| Core change that affects mobile bindings or shared models | `cd core && just test <CRATE>`<br>`just generate`<br>then targeted mobile compile until app integration is ready |
+| Shared localization input change | `just localize`<br>then targeted app/package/module compile where generated strings are consumed |
+
+## Closing Matrix
 
 | Change Type | Minimum Closing Checks |
 |-------------|------------------------|
-| iOS-only Swift or SwiftUI change | `cd ios && just build`<br>`cd ios && just test <TARGET>` or `cd ios && just test`<br>`cd ios && just lint`<br>`cd ios && just format` |
-| Android-only Kotlin, Compose, or resource change | `cd android && ./gradlew assembleGoogleDebug` or build the affected module/variant<br>`cd android && ./gradlew test`<br>`cd android && ./gradlew lint`<br>`cd android && ./gradlew detekt`<br>`cd android && ./gradlew ktlintFormat` |
+| iOS presentation-only SwiftUI | `cd ios && just build-package <PACKAGE>`<br>Simulator/device smoke when the changed flow is reachable |
+| iOS ViewModel, navigation, app wiring, or behavioral UI change | `cd ios && just build`<br>`cd ios && just test <TARGET>` or `cd ios && just test`<br>`cd ios && just lint` and `cd ios && just format` when Swift code changed |
+| Android presentation-only Compose or resource change | `cd android && ./gradlew :<module>:assembleDebug`<br>Emulator/device smoke when the changed flow is reachable |
+| Android ViewModel, navigation, app wiring, or behavioral UI change | `cd android && ./gradlew assembleGoogleDebug` or build the affected app/module variant<br>`cd android && ./gradlew :<module>:testDebugUnitTest` or `cd android && ./gradlew test`<br>`cd android && ./gradlew lint`<br>`cd android && ./gradlew detekt`<br>`cd android && ./gradlew ktlintFormat` |
 | Core-only Rust change with no mobile API impact | `cd core && just test <CRATE>`<br>`cd core && cargo clippy -p <crate> -- -D warnings`<br>`cd core && just format` |
 | Core change that affects mobile bindings or shared models | `cd core && just test <CRATE>`<br>`cd core && cargo clippy -p <crate> -- -D warnings`<br>`cd core && just format`<br>`just generate`<br>`just ios build`<br>`just android build` |
 | Shared localization input change | `just localize`<br>Rebuild the affected app(s) if the generated strings are consumed by the change |
+| Documentation-only change | `git diff --check`<br>Inspect changed links, paths, commands, and instructions |
 
-Use the narrowest relevant test target while iterating, then finish with the broader validation required by the change.
-
-Closing a task requires at least one real build or test command for the changed area. Do not substitute `git diff`, static inspection, or reasoning for execution. If execution is blocked by unrelated repo state, include the exact command and the blocking failure in the handoff.
-
-## iOS
+Navigation, app wiring, wallet-critical UI, security-sensitive code, Room migrations, signing, transaction construction, wallet import/export, seed phrases, private keys, and auth flows are never presentation-only. Use the stricter platform/security checks for those tasks.
 
-```bash
-cd ios && just build
-cd ios && just test
-cd ios && just lint
-cd ios && just format
-```
+Except for documentation-only changes, closing a task requires at least one real build or test command for the changed area. Do not substitute `git diff`, static inspection, or reasoning for execution. If execution is blocked by unrelated repo state, include the exact command and the blocking failure in the handoff.
 
-## Android
+## Ready-to-Commit Batch
 
-```bash
-cd android && ./gradlew test
-cd android && ./gradlew lint
-cd android && ./gradlew detekt
-cd android && ./gradlew ktlintFormat
-```
+Do not run the closing matrix after every edit. Once the implementation is stable and no more code edits are expected, run the applicable closing checks as one batch:
 
-## Core
+1. Regenerate models/bindings or localization if the changed inputs require it.
+2. Run formatters and linters required for the touched platform.
+3. Run the targeted tests that cover the changed behavior.
+4. Build the affected package/module/app according to the closing matrix.
+5. Exercise the changed UI flow when the platform guide requires a simulator, emulator, or device smoke check.
 
-```bash
-cd core && just test <CRATE>
-cd core && cargo clippy -p <crate> -- -D warnings
-cd core && just format
-```
+If any step modifies source files or forces a compile fix, return to the narrow iteration loop, then run the affected final checks again.
 
 If you change shared models or bindings, also run the generation steps and validate both mobile apps.