Improve the aganets.md

Author: WilliamBergamin

.claude/settings.json

@@ -1,6 +1,13 @@
 {
 	"permissions": {
 		"allow": [
+			"Bash(./mvnw:*)",
+			"Bash(./scripts/check_dependency_updates.sh:*)",
+			"Bash(./scripts/install_local.sh:*)",
+			"Bash(./scripts/run_all_bolt_tests.sh:*)",
+			"Bash(./scripts/run_all_client_tests.sh:*)",
+			"Bash(./scripts/run_no_prep_tests.sh:*)",
+			"Bash(./scripts/set_version.sh:*)",
 			"Bash(gh issue view:*)",
 			"Bash(gh label list:*)",
 			"Bash(gh pr checks:*)",
@@ -18,9 +25,9 @@
 			"Bash(grep:*)",
 			"Bash(ls:*)",
 			"Bash(tree:*)",
-			"WebFetch(domain:github.com)",
+			"WebFetch(domain:central.sonatype.com)",
 			"WebFetch(domain:docs.slack.dev)",
-			"WebFetch(domain:central.sonatype.com)"
+			"WebFetch(domain:github.com)"
 		]
 	}
 }

AGENTS.md

@@ -12,9 +12,9 @@ There are two main components:
 ## Build System
 
 - **Build tool**: Apache Maven via Maven Wrapper (`./mvnw`)
-- **Java target**: Source and target compatibility is Java 1.8 (OpenJDK 8+)
-- **Group ID**: `com.slack.api`
-- **Current version**: Check `<version>` in root `pom.xml`
+- **Java target**: Source and target compatibility is Java 1.8 (OpenJDK 8+) — see `pom.xml` properties `maven.compiler.source` and `maven.compiler.target`
+- **Group ID**: `com.slack.api` — see `pom.xml` `<groupId>`
+- **Current version**: See `<version>` in root `pom.xml` (also reflected in `*LibraryVersion.java` files generated by `scripts/set_version.sh`)
 
 ### Key Commands
 
@@ -50,7 +50,7 @@ Some modules are excluded on JDK 8 (Jakarta EE modules, GCF, Helidon, http4k, Mi
 
 ## Module Architecture
 
-All published modules use group ID `com.slack.api` and are released to Maven Central simultaneously.
+All published modules use group ID `com.slack.api` (see `pom.xml` `<groupId>`) and are released to Maven Central simultaneously. The complete list of modules is defined in root `pom.xml` `<modules>` section.
 
 ### Foundation Modules
 
@@ -131,39 +131,43 @@ All published modules use group ID `com.slack.api` and are released to Maven Cen
 
 ## Key Dependencies
 
-| Library | Version Property | Notes |
-|---------|-----------------|-------|
-| OkHttp | `okhttp.version` (4.x) | HTTP client |
+All dependency versions are managed in root `pom.xml` `<properties>` section.
+
+| Library | Version Property  | Notes |
+|---------|------------------|-------|
+| OkHttp | `okhttp.version` | HTTP client |
 | Gson | `gson.version` | JSON serialization; uses `LOWER_CASE_WITH_UNDERSCORES` field naming via `GsonFactory.createSnakeCase()` |
-| SLF4J | `slf4j.version` (1.7.x) | Logging facade. **Do not upgrade to v2** - see issue #1034 |
+| SLF4J | `slf4j.version` | Logging facade. **Do not upgrade to v2** - see issue #1034 |
 | Lombok | `lombok.version` | Used extensively for `@Data`, `@Builder`, `@Slf4j` |
-| Kotlin | `kotlin.version` (1.9.x) | API/language version pinned to 1.6 for backward compat |
-| JUnit | `junit.version` (4.x) | **JUnit 4, not 5** |
-| Mockito | `mockito-core.version` (<5.0) | Capped below v5 for Java 8 compatibility |
+| Kotlin | `kotlin.version` | Compiler version is 1.9.x; `apiVersion` and `languageVersion` pinned to 1.6 for backward compat |
+| JUnit | `junit.version` | **JUnit 4, not 5** |
+| Mockito | `mockito-core.version` | Capped below v5 for Java 8 compatibility |
 | Hamcrest | `hamcrest.version` | Used for test assertions |
 
+**Note**: Always check `pom.xml` `<properties>` for actual current versions.
+
 ## Code Conventions
 
 ### Java Style
 
-- **Java 8 compatibility is mandatory**. Do not use Java 9+ APIs (e.g., `List.of()`, `Map.of()`, `var`, `HttpClient`, text blocks).
+- **Java 8 compatibility is mandatory** (see `pom.xml` `maven.compiler.source` and `maven.compiler.target` = 1.8). Do not use Java 9+ APIs (e.g., `List.of()`, `Map.of()`, `var`, `HttpClient`, text blocks).
 - Lombok annotations are used pervasively: `@Data`, `@Builder`, `@Slf4j`, `@EqualsAndHashCode(callSuper = false)`.
-- JSON field naming uses **snake_case** via Gson's `LOWER_CASE_WITH_UNDERSCORES` policy. Java fields are camelCase.
+- JSON field naming uses **snake_case** via Gson's `LOWER_CASE_WITH_UNDERSCORES` policy (see `slack-api-client/src/main/java/com/slack/api/util/json/GsonFactory.java`). Java fields are camelCase.
 - Logging uses SLF4J via Lombok's `@Slf4j` (gives you a `log` field).
 - Checked exceptions: API methods throw `IOException` and `SlackApiException`.
 
 ### Naming Conventions
 
-- Request classes: `{MethodName}Request` with `@Data @Builder` and implementing `SlackApiRequest`
-- Response classes: `{MethodName}Response` with `@Data` and implementing `SlackApiTextResponse`
-- API method constants: `Methods.java` has `public static final String` for each API method (e.g., `USERS_INFO = "users.info"`)
+- Request classes: `{MethodName}Request` with `@Data @Builder` and implementing `SlackApiRequest` (see `slack-api-client/src/main/java/com/slack/api/methods/SlackApiRequest.java`)
+- Response classes: `{MethodName}Response` with `@Data` and implementing `SlackApiTextResponse` (see `slack-api-client/src/main/java/com/slack/api/methods/SlackApiTextResponse.java`)
+- API method constants: `Methods.java` has `public static final String` for each API method (e.g., `USERS_INFO = "users.info"`) — see `slack-api-client/src/main/java/com/slack/api/methods/Methods.java`
 - Test packages: `test_locally` for CI-safe tests, `test_with_remote_apis` for integration tests needing tokens
 
 ### JSON Serialization
 
-- Use `GsonFactory.createSnakeCase()` for most Slack APIs (snake_case JSON keys)
+- Use `GsonFactory.createSnakeCase()` for most Slack APIs (snake_case JSON keys with `LOWER_CASE_WITH_UNDERSCORES` policy)
 - Use `GsonFactory.createCamelCase()` for SCIM APIs
-- The factory is in `slack-api-client/src/main/java/com/slack/api/util/json/GsonFactory.java`
+- The factory implementation is in `slack-api-client/src/main/java/com/slack/api/util/json/GsonFactory.java`
 
 ## Model Types (`slack-api-model`)
 
@@ -219,7 +223,7 @@ public class ChannelCreatedEvent implements Event {
 
 - Use `@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor`, `@EqualsAndHashCode(callSuper = false)` on concrete types.
 - Define `public static final String TYPE` (or `TYPE_NAME`) and `private final String type = TYPE;`.
-- Java fields are camelCase; Gson's `LOWER_CASE_WITH_UNDERSCORES` policy maps them to snake_case JSON automatically.
+- Java fields are camelCase; Gson's `LOWER_CASE_WITH_UNDERSCORES` policy (see `GsonFactory.java`) maps them to snake_case JSON automatically.
 - Use `@SerializedName` only when the Slack API field name does not follow snake_case convention.
 - Do **not** initialize `List` fields to empty collections — Slack sometimes returns errors with empty arrays, and null vs empty has semantic meaning.
 
@@ -299,41 +303,13 @@ public class ConversationsRequestSharedInviteApproveRequest implements SlackApiR
 }
 ```
 
-A simpler request class (for `conversations.requestSharedInvite.deny`):
-
-```java
-package com.slack.api.methods.request.conversations.request_shared_invite;
-
-import com.slack.api.methods.SlackApiRequest;
-import lombok.Builder;
-import lombok.Data;
-
-/**
- * https://docs.slack.dev/reference/methods/conversations.requestSharedInvite.deny
- */
-@Data
-@Builder
-public class ConversationsRequestSharedInviteDenyRequest implements SlackApiRequest {
-
-    private String token;
-
-    /**
-     * ID of the requested shared channel invite to deny.
-     */
-    private String inviteId;
-
-    /**
-     * Optional message explaining why the request to invite was denied.
-     */
-    private String message;
-}
-```
+For simpler methods without nested objects, the same pattern applies but without the inner `@Data` classes (e.g., `ConversationsRequestSharedInviteDenyRequest` has only `token`, `inviteId`, and `message` fields).
 
 ### 4. Create the Response class
 
 File: `slack-api-client/src/main/java/com/slack/api/methods/response/conversations/request_shared_invite/ConversationsRequestSharedInviteApproveResponse.java`
 
-The response class implements `SlackApiTextResponse` and uses `@Data`. Every response must include the standard fields (`ok`, `warning`, `error`, `needed`, `provided`, `httpResponseHeaders`). Add any method-specific response fields from the API docs:
+The response class implements `SlackApiTextResponse` and uses `@Data`. Every response must include the standard fields defined by the `SlackApiTextResponse` interface (`ok`, `warning`, `error`, `needed`, `provided`, `httpResponseHeaders`). Add any method-specific response fields from the API docs:
 
 ```java
 package com.slack.api.methods.response.conversations.request_shared_invite;
@@ -463,7 +439,7 @@ public static FormBody.Builder toForm(ConversationsRequestSharedInviteDenyReques
 
 File: `slack-api-client/src/main/java/com/slack/api/methods/MethodsRateLimits.java`
 
-Look up the rate limit tier from the API docs and add a `setRateLimitTier` call in the appropriate alphabetical position:
+Look up the rate limit tier from the API docs (or check `metadata/web-api/rate_limit_tiers.json` for existing patterns) and add a `setRateLimitTier` call in the appropriate alphabetical position:
 
 ```java
 setRateLimitTier(CONVERSATIONS_REQUEST_SHARED_INVITE_APPROVE, Tier2);
@@ -474,18 +450,36 @@ setRateLimitTier(CONVERSATIONS_REQUEST_SHARED_INVITE_DENY, Tier2);
 
 File: `metadata/web-api/rate_limit_tiers.json`
 
-Add the method name and its tier in alphabetical order within the JSON object:
+Add the method name and its tier in alphabetical order within the JSON object. This file is the source of truth for rate limit tiers and should match the tier set in `MethodsRateLimits.java`:
 
 ```json
 "conversations.requestSharedInvite.approve": "Tier2",
 "conversations.requestSharedInvite.deny": "Tier2",
 ```
 
-### 12. Add tests and update `MethodsTest`
+### 12. Check mock server JSON fixture
+
+File (new): `json-logs/samples/api/{method.name}.json`
+
+The `MockSlackApiServer` used in tests serves mock responses from JSON files in this directory. Every API method **must** have a corresponding JSON fixture file, or tests will fail with `NoSuchFileException` / HTTP 500. The file name is the full API method name with dots (e.g., `conversations.requestSharedInvite.approve.json`).
+
+The mock server reads these files and replaces `"ok": false,` with `"ok": true,` automatically, so the fixture should always have `"ok": false`. See existing files in this directory for examples:
+
+```json
+{
+  "ok": false,
+  "error": "",
+  "needed": "",
+  "provided": "",
+  "warning": ""
+}
+```
+
+### 13. Add tests and update `MethodsTest`
 
 #### Add method-specific tests
 
-File: `slack-api-client/src/test/java/test_locally/api/methods/ConversationsTest.java` (or the relevant existing test file for the API category)
+File: `slack-api-client/src/test/java/test_locally/api/methods/{Category}Test.java` (the test file matching the top-level API namespace, e.g., `AppsTest.java` for `apps.*`, `ConversationsTest.java` for `conversations.*`)
 
 Test both sync and async variants using the configurator lambda pattern:
 
@@ -507,25 +501,54 @@ public void conversationsRequestSharedInviteApprove_async() throws Exception {
 
 File: `slack-api-client/src/test/java/test_locally/api/MethodsTest.java`
 
-This test validates that every known Slack API method has a corresponding `Methods.java` constant and rate limit entry. Update the `methods` string and the endpoint count comment to include the new method names. If the method names are not already in the list, add them in the correct alphabetical position.
+This test validates that every known Slack API method has a corresponding constant in `Methods.java` and rate limit entry in `metadata/web-api/rate_limit_tiers.json`. Update the `methods` string and the endpoint count comment to include the new method names. If the method names are not already in the list, add them in the correct alphabetical position.
+
+### 14. Add imports to all modified files
+
+Each file that references the new Request and Response classes needs corresponding import statements. When modifying the following files, add imports for both the new Request and Response classes:
+
+- `MethodsClient.java` — import both `request` and `response` classes
+- `AsyncMethodsClient.java` — import both `request` and `response` classes
+- `MethodsClientImpl.java` — import both `request` and `response` classes
+- `AsyncMethodsClientImpl.java` — import both `request` and `response` classes
+- `RequestFormBuilder.java` — import the `request` class only
+
+Place each new import adjacent to the existing imports from the same `apps.*` (or equivalent) package, in alphabetical order.
+
+### 15. Verify
+
+Before considering the work complete, run the tests. The `slack-api-client` module depends on `slack-api-model`, so you must install all modules locally first if they haven't been built yet:
+
+```bash
+# Install all modules locally (required before running single-module tests)
+./scripts/install_local.sh
+
+# Run the specific tests for the new method and the coverage test
+./mvnw test -pl slack-api-client '-Dtest=test_locally.api.methods.AppsTest,test_locally.api.MethodsTest'
+```
+
+Note: `install_local.sh` may fail on unrelated example modules (e.g., `bolt-quarkus-examples`). This is fine as long as `slack-api-client` and its dependencies (`slack-api-model`) install successfully.
 
 ### Summary checklist
 
 When adding a new Slack API method, make sure you have:
 
 - [ ] Looked up the method docs at `https://docs.slack.dev/reference/methods/{method.name}`
-- [ ] Added the method constant in `Methods.java`
-- [ ] Created the Request class in `request/{category}/`
-- [ ] Created the Response class in `response/{category}/`
-- [ ] Added two overloads in `MethodsClient.java`
-- [ ] Added two overloads in `AsyncMethodsClient.java`
-- [ ] Implemented both overloads in `MethodsClientImpl.java`
-- [ ] Implemented both overloads in `AsyncMethodsClientImpl.java`
-- [ ] Added `toForm()` in `RequestFormBuilder.java`
-- [ ] Added rate limit tier in `MethodsRateLimits.java`
+- [ ] Added the method constant in `slack-api-client/src/main/java/com/slack/api/methods/Methods.java`
+- [ ] Created the Request class in `slack-api-client/src/main/java/com/slack/api/methods/request/{category}/`
+- [ ] Created the Response class in `slack-api-client/src/main/java/com/slack/api/methods/response/{category}/`
+- [ ] Added two overloads in `slack-api-client/src/main/java/com/slack/api/methods/MethodsClient.java`
+- [ ] Added two overloads in `slack-api-client/src/main/java/com/slack/api/methods/AsyncMethodsClient.java`
+- [ ] Implemented both overloads in `slack-api-client/src/main/java/com/slack/api/methods/impl/MethodsClientImpl.java`
+- [ ] Implemented both overloads in `slack-api-client/src/main/java/com/slack/api/methods/impl/AsyncMethodsClientImpl.java`
+- [ ] Added `toForm()` in `slack-api-client/src/main/java/com/slack/api/methods/RequestFormBuilder.java`
+- [ ] Added rate limit tier in `slack-api-client/src/main/java/com/slack/api/methods/MethodsRateLimits.java`
 - [ ] Added rate limit entry in `metadata/web-api/rate_limit_tiers.json`
-- [ ] Added sync and async tests in `test_locally/api/methods/`
-- [ ] Updated the endpoint list and count in `MethodsTest.java`
+- [ ] Created mock server JSON fixture in `json-logs/samples/api/{method.name}.json`
+- [ ] Added sync and async tests in `slack-api-client/src/test/java/test_locally/api/methods/{Category}Test.java`
+- [ ] Updated the endpoint list and count in `slack-api-client/src/test/java/test_locally/api/MethodsTest.java`
+- [ ] Added import statements for the new Request/Response classes in all modified files
+- [ ] Verified tests pass: `./mvnw test -pl slack-api-client '-Dtest=test_locally.api.methods.{Category}Test,test_locally.api.MethodsTest'`
 
 ## Testing
 
@@ -587,7 +610,7 @@ Releases publish all modules simultaneously to Maven Central via Sonatype.
 
 - **Snapshot**: Version must end with `-SNAPSHOT`. Run `scripts/set_version.sh 1.x.y-SNAPSHOT` then `scripts/release.sh`
 - **Stable**: Run `scripts/set_version.sh 1.x.y` then `scripts/release.sh`. Requires JDK 17, GPG signing, and Sonatype credentials in `~/.m2/settings.xml`
-- Version is set across all `pom.xml` files AND three generated version classes:
+- Version is set across all `pom.xml` files AND three generated version classes (generated by `scripts/set_version.sh`):
   - `slack-api-model/src/main/java/com/slack/api/meta/SlackApiModelLibraryVersion.java`
   - `slack-api-client/src/main/java/com/slack/api/meta/SlackApiClientLibraryVersion.java`
   - `bolt/src/main/java/com/slack/api/bolt/meta/BoltLibraryVersion.java`