docs: fix accuracy issues in AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md

- AGENTS.md: clarify that .select() with fields.* requires .withContentType()
  first (client-side IllegalStateException, not an API error); sys-only
  selections have no such requirement
- ARCHITECTURE.md: fix resolveLinks() description — it iterates entry
  content-type field definitions and looks up from the indexed maps, not
  "traverses the includes"; silently drops unresolved links
- CONTRIBUTING.md: correct integration test setup — credentials are
  hardcoded in test classes, no env vars needed; clarify tests run locally
  only, not in CI
- CONTRIBUTING.md: replace bare mvn with ./mvnw in release steps

Author: tylerpina

AGENTS.md

@@ -19,7 +19,7 @@ Read this file first. It tells you where to find context in this repo.
 
 - **Link resolution order matters** — `ResourceUtils.resolveLinks()` must run after localization and raw-field capture. Never reorder the post-processing pipeline in `ResourceFactory.array()` without understanding all downstream side effects.
 - **Unresolved links are silent, not exceptions** — if an included entry's depth exceeds the API limit (10), unresolved links remain as placeholder objects. Code that dereferences resolved links must handle null/stub gracefully.
-- **`sys` fields are always present** — the SDK enforces that `sys.*` attributes are always returned (for the `select` feature, `.withContentType()` is required when using `.select()` or an API error will ensue).
+- **`sys` fields are always present** — the SDK enforces that `sys.*` attributes are always returned. When using `.select()` with `fields.*` selections, `.withContentType()` must be called first or the SDK throws a client-side `IllegalStateException` before the request is sent. Selecting only `sys` fields does not require a content type.
 - **`rawFields` is the only path to raw rich text JSON** — `TransformQuery` (unwrapping) does not expose raw rich text; use `CDAEntry.rawFields` or make a direct HTTP request.
 - **Cross-space token limit is 20** — `setCrossSpaceTokens()` accepts at most 20 extra spaces (21 total). Only the first level of cross-space references is resolved.
 - **Sync tokens are stateful and environment-aware** — passing a `SynchronizedSpace` from the wrong environment to `client.sync()` will produce incorrect deltas.

ARCHITECTURE.md

@@ -49,7 +49,7 @@ Consumers are JVM and Android applications. The SDK wraps all outbound HTTP via
    - `ResourceUtils.mapResources()` — indexes assets and entries by ID
    - `ResourceUtils.setRawFields()` — preserves the unprocessed field map for rich text access
    - `RichTextFactory.resolveRichTextField()` — parses rich text JSON into the `CDARich*` node tree
-   - `ResourceUtils.resolveLinks()` — traverses the includes and replaces link stubs with the actual `CDAResource` objects (in-memory object graph)
+   - `ResourceUtils.resolveLinks()` — iterates each entry's content-type field definitions to find Link and Array-of-Link fields, then replaces link stubs with the already-indexed `CDAResource` objects from `array.assets()` / `array.entries()` (in-memory object graph). Links not present in the index are silently dropped, not thrown as errors.
 
 5. **Result** — `CDAArray` (or single `CDAResource`) is returned to the caller with fully resolved links and localized fields.
 

CONTRIBUTING.md

@@ -44,7 +44,7 @@ devcontainer exec --workspace-folder . bash
 ./mvnw -B test
 ```
 
-- **Integration tests** require a live Contentful space and environment variables — not run in CI by default.
+- **Integration tests** connect to live Contentful spaces using hardcoded read-only credentials (space IDs and tokens are baked into the test classes under `src/test/java/…/cda/integration/`). No environment variables are required. Integration tests are not run in CI — run them locally when you need to verify against the live API.
 
 ## Commit Convention
 
@@ -80,10 +80,10 @@ Releases are on-demand and require the Contentful GPG key imported locally (obta
 # 2. Add -SNAPSHOT postfix to <version> in pom.xml if not already present
 
 # 3. Prepare the release (prompts for release version and next snapshot version)
-mvn release:prepare
+./mvnw release:prepare
 
 # 4. Perform the release (builds, signs, and publishes to Maven Central)
-mvn release:perform
+./mvnw release:perform
 ```
 
 Artifacts are published to Maven Central under `com.contentful.java:java-sdk`. Pre-releases are available via Sonatype snapshots and jitpack.io.