Add agent guide and skills documentation

.cursor/rules/README.md

@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+*Cursor* users: start at *[AGENTS.md](../../AGENTS.md)*. All conventions live in **skills/*/SKILL.md**.
+
+This folder only points contributors to *AGENTS.md* so editor-specific config does not duplicate the canonical docs.

AGENTS.md

@@ -0,0 +1,51 @@
+# Contentstack Management Java SDK – Agent guide
+
+*Universal entry point* for contributors and AI agents. Detailed conventions live in **skills/*/SKILL.md**.
+
+## What this repo is
+
+| Field | Detail |
+| --- | --- |
+| *Name:* | [contentstack-management-java](https://github.com/contentstack/contentstack-management-java) |
+| *Purpose:* | Java client library for the Contentstack Content Management API (CMA): create, update, delete, and fetch account content and configuration from JVM applications. |
+| *Out of scope (if any):* | Content Delivery API (CDA) and delivery-only use cases belong in the Delivery SDK, not this package. This SDK is read/write against CMA; do not treat it as the primary way to serve content to end users. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| Language | Java 8 (source/target in `pom.xml`); README suggests Java 8+ for consumers. |
+| Build | Apache Maven; `pom.xml` at repo root. |
+| Tests | JUnit 5 / Vintage, Mockito, OkHttp MockWebServer; tests under `src/test/java/com/contentstack/cms/`. |
+| Lint / coverage | Compiler: `-Xlint:all` (see `maven-compiler-plugin`). Coverage: JaCoCo (`jacoco-maven-plugin`); HTML report under `target/site/jacoco` after tests + `jacoco:report`. No separate Checkstyle/SpotBugs in this `pom.xml`. |
+| Other | HTTP: Retrofit 3, OkHttp 5, Gson; RxJava 3; Lombok for generated code. |
+
+## Commands (quick reference)
+
+| Command type | Command |
+| --- | --- |
+| Build | `mvn clean compile` |
+| Test | `mvn clean test -DskipTests=false` |
+| Lint | `mvn compile` (compiler warnings; see Tech stack) |
+| Coverage | `mvn clean test -DskipTests=false jacoco:report` (open `target/site/jacoco/index.html`) |
+
+**Note:** `maven-surefire-plugin` sets `skipTests` to `true` by default in this repo, so you must pass `-DskipTests=false` (or override in your IDE) to run unit tests locally.
+
+**CI:** [.github/workflows/coverage.yml](.github/workflows/coverage.yml) runs `mvn clean package` and JaCoCo steps on push. Other workflows under [.github/workflows/](.github/workflows/) handle publish, scans, and branch checks.
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Dev workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, Maven lifecycle, CI expectations, PR flow. |
+| Contentstack Java CMA SDK | [skills/contentstack-java-cma-sdk/SKILL.md](skills/contentstack-java-cma-sdk/SKILL.md) | Public API, `Contentstack` entry point, auth, versioning boundaries. |
+| Java (repo conventions) | [skills/java/SKILL.md](skills/java/SKILL.md) | Package layout, language conventions, Lombok usage. |
+| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Test layout, naming, skipping policy, credentials. |
+| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist and severity guidance. |
+| HTTP client stack | [skills/http-client-stack/SKILL.md](skills/http-client-stack/SKILL.md) | Retrofit, OkHttp, retries, logging—what this repo actually wires. |
+
+An index with “when to use” hints is in [skills/README.md](skills/README.md).
+
+## Using Cursor (optional)
+
+If you use *Cursor*, [.cursor/rules/README.md](.cursor/rules/README.md) only points to *AGENTS.md*—same docs as everyone else.

pom.xml

@@ -93,7 +93,7 @@
         <converter-gson-version>3.0.0</converter-gson-version>
         <okhttp.version>5.3.2</okhttp.version>
         <jococo-plugin.version>0.8.13</jococo-plugin.version>
-        <lombok-source.version>1.18.42</lombok-source.version>
+        <lombok-source.version>1.18.44</lombok-source.version>
         <junit-jupiter.version>5.11.4</junit-jupiter.version>
         <junit-jupiter-engine.version>5.10.1</junit-jupiter-engine.version>
         <gson.version>2.13.2</gson.version>
@@ -148,7 +148,7 @@
         <dependency>
             <groupId>org.jetbrains</groupId>
             <artifactId>annotations</artifactId>
-            <version>26.0.2</version>
+            <version>26.1.0</version>
             <scope>provided</scope>
         </dependency>
         <dependency>
@@ -214,12 +214,12 @@
          <dependency>
             <groupId>org.jsoup</groupId>
             <artifactId>jsoup</artifactId>
-            <version>1.21.2</version>
+            <version>1.22.1</version>
         </dependency>
         <dependency>
             <groupId>org.jetbrains.kotlin</groupId>
             <artifactId>kotlin-stdlib</artifactId>
-            <version>2.2.21</version>
+            <version>2.3.20</version>
         </dependency>
          <dependency>
             <groupId>com.warrenstrange</groupId>
@@ -254,7 +254,7 @@
                      </includes>
                      <reportsDirectory>${project.build.directory}/surefire-reports</reportsDirectory>
                     <!-- Skip during default lifecycle (e.g. publish); run tests locally with: mvn test -DskipTests=false -->
-                    <skipTests>true</skipTests>
+                    <!-- <skipTests>true</skipTests> -->
                     <testFailureIgnore>true</testFailureIgnore>
                 </configuration>
             </plugin>

skills/README.md

@@ -0,0 +1,16 @@
+# Skills – Contentstack Management Java SDK
+
+Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task.
+
+## When to use which skill
+
+| Skill folder | Use when |
+| --- | --- |
+| [dev-workflow](dev-workflow/SKILL.md) | Branching against `master`/`staging`, running Maven/CI commands, release or publish touchpoints. |
+| [contentstack-java-cma-sdk](contentstack-java-cma-sdk/SKILL.md) | Changing public API, `Contentstack` / `Stack` flows, auth tokens, or SDK surface exposed to integrators. |
+| [java](java/SKILL.md) | Package structure under `com.contentstack.cms`, Java 8 compatibility, Lombok, imports, and code style in this repo. |
+| [testing](testing/SKILL.md) | Adding or fixing tests, Surefire `skipTests` behavior, MockWebServer or live API tests, env/credentials. |
+| [code-review](code-review/SKILL.md) | Preparing or reviewing a PR: scope, tests, API compatibility, and security around tokens. |
+| [http-client-stack](http-client-stack/SKILL.md) | Retrofit services, OkHttp client/interceptors, retries, proxies, or HTTP logging. |
+
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

skills/code-review/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: code-review
+description: Use when reviewing or preparing a PR—API safety, tests, auth handling, and compatibility checklist.
+---
+
+# Code review – Contentstack Management Java SDK
+
+## When to use
+
+- You are reviewing a pull request or self-reviewing before request.
+- You need a quick severity rubric (blocker / major / minor) aligned with this SDK.
+
+## Instructions
+
+### Blocker
+
+- Real credentials, tokens, or stack keys committed in source or fixtures.
+- Breaking public API changes without version strategy or without team agreement.
+- New network behavior that bypasses existing interceptors, retry policy, or auth without explicit design.
+
+### Major
+
+- Missing or insufficient tests for new CMA behavior or error paths.
+- Behavior change for `Contentstack` / `Stack` builders or defaults without README or Javadoc updates where integrators would notice.
+- Regressions for Java 8 compatibility or new compiler warnings left unaddressed.
+
+### Minor
+
+- Style inconsistencies fixable in follow-up, or internal refactors with no API impact.
+- Javadoc typos or non-user-facing comment cleanup.
+
+### PR checklist (short)
+
+- [ ] `mvn clean test -DskipTests=false` passes locally.
+- [ ] Public changes documented (Javadoc / README / changelog per team process).
+- [ ] No secrets in repo; test config uses env or mocks.
+- [ ] HTTP changes reviewed against [http-client-stack/SKILL.md](../http-client-stack/SKILL.md).
+
+## References
+
+- [dev-workflow/SKILL.md](../dev-workflow/SKILL.md)
+- [contentstack-java-cma-sdk/SKILL.md](../contentstack-java-cma-sdk/SKILL.md)

skills/contentstack-java-cma-sdk/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: contentstack-java-cma-sdk
+description: Use when changing the Management SDK surface—Contentstack entry, Stack, auth, or CMA integration boundaries.
+---
+
+# Contentstack Java CMA SDK – Contentstack Management Java SDK
+
+## When to use
+
+- You add or change public methods on `Contentstack`, `Stack`, organization, user, or other API-facing types under `com.contentstack.cms`.
+- You need to document how integrators authenticate (authtoken, management token, OAuth, login).
+- You are deciding what belongs in this SDK vs the Delivery API or other Contentstack clients.
+
+## Instructions
+
+### Purpose and boundaries
+
+- This library targets the [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/) (CMA). It is **not** the recommended way to deliver content to websites or apps at scale; the README directs readers to the [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) for that.
+- The main entry point is [`Contentstack`](../../src/main/java/com/contentstack/cms/Contentstack.java): builders set host, tokens, timeouts, proxy, OAuth, and retry behavior before obtaining `Stack`, `User`, `Organization`, etc.
+
+### Public API and compatibility
+
+- Treat additions to public classes as **semver-sensitive**: new optional builder methods are easier to ship than breaking signature changes.
+- Errors and responses should stay consistent with existing patterns (`retrofit2.Response`, model types under `com.contentstack.cms.models`, etc.).
+- Document behavior in Javadoc where integrators rely on contracts (auth order, token precedence, branch/early-access headers).
+
+### Versioning
+
+- Artifact coordinates: `com.contentstack.sdk:cms` — version in root [`pom.xml`](../../pom.xml). Follow org release process for bumping version and tagging.
+
+## References
+
+- [java/SKILL.md](../java/SKILL.md)
+- [http-client-stack/SKILL.md](../http-client-stack/SKILL.md)
+- [Content Management API – Authentication](https://www.contentstack.com/docs/developers/apis/content-management-api/#authentication) (official)

skills/dev-workflow/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: dev-workflow
+description: Use when branching, building with Maven, CI, or release/publish workflows for this repo.
+---
+
+# Dev workflow – Contentstack Management Java SDK
+
+## When to use
+
+- You need the canonical build/test commands or CI expectations.
+- You are opening a PR and need branch rules (`master` vs `staging`).
+- You are changing `pom.xml`, plugins, or publishing configuration.
+
+## Instructions
+
+### Repository and branches
+
+- Default collaboration flow is documented in [.github/workflows/check-branch.yml](../../.github/workflows/check-branch.yml): PRs targeting `master` from branches other than `staging` may be blocked; prefer the documented Contentstack branching policy for your team.
+
+### Maven
+
+- **Compile:** `mvn clean compile`
+- **Tests:** `mvn clean test -DskipTests=false` (Surefire is configured with `skipTests` true by default in [`pom.xml`](../../pom.xml); always pass `-DskipTests=false` for real test runs unless you intentionally skip.)
+- **Package:** `mvn clean package` — note tests may be skipped unless you add `-DskipTests=false`.
+- **Coverage report:** after tests with skip disabled, `mvn jacoco:report` and open `target/site/jacoco/index.html`.
+
+### CI
+
+- On push, [.github/workflows/coverage.yml](../../.github/workflows/coverage.yml) uses Java 11 on Ubuntu and runs Maven + JaCoCo. Align local verification with those steps when debugging CI-only failures.
+- Publishing and security scans live under [.github/workflows/](../../.github/workflows/); read the relevant workflow before changing release or scan behavior.
+
+### PR expectations
+
+- Run tests locally with `-DskipTests=false` before pushing.
+- Update [changelog.md](../../changelog.md) or version metadata when your team’s release process requires it.
+
+## References
+
+- [AGENTS.md](../../AGENTS.md)
+- [testing/SKILL.md](../testing/SKILL.md)
+- [code-review/SKILL.md](../code-review/SKILL.md)

skills/http-client-stack/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: http-client-stack
+description: Use when changing Retrofit, OkHttp, interceptors, retries, proxies, or HTTP logging in this SDK.
+---
+
+# HTTP client stack – Contentstack Management Java SDK
+
+## When to use
+
+- You modify [`Contentstack`](../../src/main/java/com/contentstack/cms/Contentstack.java) or related code that builds `Retrofit`, `OkHttpClient`, or interceptors.
+- You touch `AuthInterceptor`, OAuth interceptors, logging, connection pool, timeouts, or `RetryConfig` / retry utilities under `com.contentstack.cms.core`.
+
+## Instructions
+
+### Stack in this repo
+
+- **Retrofit 3** + **Gson** converter for API interfaces and JSON binding.
+- **OkHttp 5** for transport; **logging-interceptor** for debug logging when enabled.
+- **RxJava 3** is a dependency for async patterns where used; keep consistency with existing call patterns.
+
+### Auth and headers
+
+- `AuthInterceptor` and OAuth-related types attach tokens and headers expected by CMA. Changes here affect every call—coordinate with tests in `core/` (e.g. `AuthInterceptorTest`).
+
+### Retries and resilience
+
+- Retry behavior is configurable via `RetryConfig` and related utilities (`core/Retry*.java`). Preserve backward-compatible defaults when adjusting retry conditions or backoff.
+
+### Proxies and TLS
+
+- `Contentstack` supports `Proxy` configuration; verify behavior if you change client building or connection pool settings.
+
+### Testing
+
+- Prefer **MockWebServer** for deterministic HTTP tests; see existing stack and core tests for patterns.
+
+## References
+
+- [contentstack-java-cma-sdk/SKILL.md](../contentstack-java-cma-sdk/SKILL.md)
+- [testing/SKILL.md](../testing/SKILL.md)
+- [Retrofit](https://square.github.io/retrofit/) (official)
+- [OkHttp](https://square.github.io/okhttp/) (official)

skills/java/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: java
+description: Use for Java package layout, Java 8 constraints, Lombok, and coding conventions in this repository.
+---
+
+# Java – Contentstack Management Java SDK
+
+## When to use
+
+- You add new types under `com.contentstack.cms` or reorganize packages.
+- You need to stay compatible with Java 8 (`maven.compiler.source` / `target` = 1.8).
+- You use or configure Lombok and need to match existing patterns.
+
+## Instructions
+
+### Layout
+
+- **Main code:** `src/main/java/com/contentstack/cms/` — core client in `Contentstack`, stack features under `stack/`, HTTP helpers in `core/`, OAuth under `oauth/`, models under `models/`.
+- **Tests:** mirror packages under `src/test/java/com/contentstack/cms/`; Surefire includes `**/Test*.java`, `**/*Test.java`, `**/*Tests.java`, and related patterns per [`pom.xml`](../../pom.xml).
+
+### Language level
+
+- Do not use language or library features that require a JVM newer than 8 for **source** compatibility unless the project explicitly upgrades (check `maven-compiler-plugin` and `<maven.compiler.source>` in [`pom.xml`](../../pom.xml)).
+
+### Lombok and tooling
+
+- Lombok is on the annotation processor path; prefer the same style as neighboring classes (`@Getter`, `@Builder`, etc.) instead of mixing hand-written boilerplate inconsistently.
+- JetBrains `@NotNull` / nullable annotations appear in places like [`Contentstack`](../../src/main/java/com/contentstack/cms/Contentstack.java); follow existing nullability hints for new APIs.
+
+### Compiler
+
+- The compiler enables broad `-Xlint` checks; fix new warnings rather than suppressing without cause.
+
+## References
+
+- [contentstack-java-cma-sdk/SKILL.md](../contentstack-java-cma-sdk/SKILL.md)
+- [testing/SKILL.md](../testing/SKILL.md)

skills/testing/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: testing
+description: Use when writing or running tests—Surefire skip flag, test naming, mocks, MockWebServer, and secrets policy.
+---
+
+# Testing – Contentstack Management Java SDK
+
+## When to use
+
+- You add or change unit or integration tests under `src/test/java`.
+- Tests “do not run” locally or in CI — usually `skipTests`.
+- You need to mock HTTP or use OkHttp `MockWebServer` like existing tests.
+
+## Instructions
+
+### Running tests
+
+- **Always** use `mvn test -DskipTests=false` (or `mvn clean test -DskipTests=false`) unless you are only compiling. The Surefire plugin in [`pom.xml`](../../pom.xml) sets `<skipTests>true</skipTests>` by default.
+
+### Layout and naming
+
+- Tests live under `src/test/java/com/contentstack/cms/` with class names matching Surefire includes (`*Test`, `*Tests`, `Test*`, suites like `UnitTestSuite`).
+- Reuse helpers such as [`TestClient`](../../src/test/java/com/contentstack/cms/TestClient.java), [`TestUtils`](../../src/test/java/com/contentstack/cms/core/TestUtils.java), or patterns in existing `*APITest` classes when appropriate.
+
+### HTTP and API tests
+
+- **MockWebServer** is available for stubbing HTTP; align with tests in `core/` and `stack/` packages.
+- Tests that hit real APIs may require environment variables or `.env` (see `java-dotenv` test dependency in [`pom.xml`](../../pom.xml)). **Never commit** real API keys, management tokens, or passwords; use CI secrets or local env only.
+
+### Coverage
+
+- JaCoCo attaches via `prepare-agent`; generate HTML with `mvn jacoco:report` after a test run with skips disabled.
+
+## References
+
+- [dev-workflow/SKILL.md](../dev-workflow/SKILL.md)
+- [http-client-stack/SKILL.md](../http-client-stack/SKILL.md)