docs(DX-6048): add AGENTS.md, skills, and Cursor rules entry

.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

@@ -1,54 +1,43 @@
-# Contentstack Android CDA SDK – Agent Guide
+# Contentstack Android Delivery SDK – Agent guide
 
-This document is the main entry point for AI agents working in this repository.
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-## Project
+## What this repo is
 
-- **Name:** Contentstack Android CDA SDK (contentstack-android)
-- **Purpose:** Android client for the Contentstack **Content Delivery API (CDA)**. It fetches content (entries, assets, content types, sync, etc.) from Contentstack for Android apps.
-- **Repo:** [contentstack-android](https://github.com/contentstack/contentstack-android)
+| Field | Detail |
+|--------|--------|
+| **Name:** | [contentstack-android](https://github.com/contentstack/contentstack-android) (`com.contentstack.sdk:android`) |
+| **Purpose:** | Android library for the Contentstack Content Delivery API (Kotlin/Java consumers via AAR). |
+| **Out of scope:** | Not the Java-only or iOS/Swift SDKs—those live in sibling repositories. |
 
-## Tech stack
+## Tech stack (at a glance)
 
-- **Languages:** Java (primary SDK source); Kotlin may appear in tests or future code. Target **Java 8** compatibility for the library (see `contentstack/build.gradle`).
-- **Build:** Gradle (Android Gradle Plugin), single module **`contentstack`** (AAR).
-- **Testing:** JUnit 4, Robolectric (unit tests on JVM), Mockito / PowerMock where used; **androidTest** with AndroidX Test / Espresso for instrumented tests; JaCoCo for coverage (`jacocoTestReport`).
-- **HTTP:** **Volley** (`CSHttpConnection`) for much of the CDA traffic; **Retrofit 2 + OkHttp + Gson** for paths such as taxonomy (`Stack`, `APIService`). OkHttp **MockWebServer** in unit tests.
+| Area | Details |
+|------|---------|
+| Language | Kotlin/Java; **compileSdk 34**; Java **17** compile options in `contentstack/build.gradle` |
+| Build | Gradle (root `build.gradle`, `settings.gradle`, module **`contentstack/`**) |
+| Tests | JUnit, Mockito, Robolectric, AndroidX Test—unit tests under `contentstack/src/test/` |
+| Lint / coverage | JaCoCo integrated with debug unit tests (`testCoverageEnabled` on debug) |
+| CI | `.github/workflows/check-branch.yml`, `publish-release.yml`, `sca-scan.yml`, `policy-scan.yml`, `codeql-analysis.yml` |
 
-## Main entry points
+## Commands (quick reference)
 
-- **`Contentstack`** – Factory: `Contentstack.stack(Context, apiKey, deliveryToken, environment)` (and overloads with `Config`) returns a **`Stack`**.
-- **`Stack`** – Main API: content types, entries, queries, assets, sync, etc.
-- **`Config`** – Optional configuration: host, version, region, branch, proxy, connection pool, endpoint.
-- **Paths:** `contentstack/src/main/java/com/contentstack/sdk/` (production), `contentstack/src/test/java/com/contentstack/sdk/` (unit tests), `contentstack/src/androidTest/java/` (instrumented tests).
+| Command type | Command |
+|--------------|---------|
+| Unit tests (typical) | `./gradlew :contentstack:testDebugUnitTest` (from repo root) |
+| Clean | `./gradlew clean` |
 
-## Commands
+## Where the documentation lives: skills
 
-Run from the **repository root** (requires Android SDK / `local.properties` for connected tests).
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Gradle, variants, CI, publishing |
+| **Android CDA SDK** | [`skills/contentstack-android-cda/SKILL.md`](skills/contentstack-android-cda/SKILL.md) | Library API and module boundaries |
+| **Android project layout** | [`skills/android/SKILL.md`](skills/android/SKILL.md) | `contentstack/` module, manifest, BuildConfig |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Unit vs instrumented tests, Robolectric, JaCoCo |
+| **Build & platform** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | AGP, signing placeholders, `local.properties` |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist |
 
-| Goal | Command |
-|------|---------|
-| **Build library (debug)** | `./gradlew :contentstack:assembleDebug` |
-| **Run all unit tests** | `./gradlew :contentstack:testDebugUnitTest` |
-| **Run instrumented / connected tests** | `./gradlew :contentstack:connectedDebugAndroidTest` (device or emulator required) |
-| **Unit + connected (full local test pass)** | `./gradlew :contentstack:testDebugUnitTest :contentstack:connectedDebugAndroidTest` |
-| **Coverage report (unit)** | `./gradlew :contentstack:jacocoTestReport` |
-
-Instrumented tests may need **`local.properties`** entries (e.g. `APIKey`, `deliveryToken`, `environment`, `host`) for stacks that hit a real CDA endpoint—see `contentstack/build.gradle` `buildConfigField` usage.
-
-## Rules and skills
-
-- **`.cursor/rules/`** – Cursor rules for this repo:
-  - **README.md** – Index of all rules (globs / always-on).
-  - **dev-workflow.md** – Branches, tests, PR expectations.
-  - **java.mdc** – Applies to `**/*.java` and `**/*.kt`: language style, `com.contentstack.sdk` layout, logging, null-safety.
-  - **contentstack-android-cda.mdc** – SDK core: CDA patterns, Stack/Config, host/version/region/branch, retry, callbacks, CDA alignment.
-  - **testing.mdc** – `contentstack/src/test/**` and `contentstack/src/androidTest/**`: naming, unit vs instrumented, JaCoCo.
-  - **code-review.mdc** – Always applied: PR/review checklist (aligned with Java CDA SDK).
-- **`skills/`** – Reusable skill docs:
-  - **contentstack-android-cda** – Implementing or changing CDA behavior (Stack/Config, entries, assets, sync, HTTP, callbacks).
-  - **testing** – Writing or refactoring tests.
-  - **code-review** – PR review / pre-PR checklist.
-  - **framework** – Config, HTTP layer (Volley + Retrofit/OkHttp), retry/timeouts.
-
-Refer to `.cursor/rules/README.md` and `skills/README.md` for details.
+## 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.

skills/android/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: android
+description: Use for Android module layout, Gradle config, and Kotlin/Java conventions in contentstack-android.
+---
+
+# Android project layout – contentstack-android
+
+## When to use
+
+- Editing `contentstack/build.gradle`, manifests, or source under `contentstack/src/`
+- Adjusting `minSdk`, multidex, or packaging excludes
+
+## Instructions
+
+### Source trees
+
+- Follow standard Android library layout: **`main`**, **`test`**, **`androidTest`** under `contentstack/src/`.
+
+### Configuration
+
+- **`local.properties`** supplies machine-specific paths and optional keys—do not commit secrets; use the same keys the Gradle file expects (`host`, `APIKey`, etc. in `buildTypes`).
+
+### Java/Kotlin
+
+- Compile options target **Java 17** in the module—match language features accordingly.

skills/code-review/SKILL.md

@@ -1,60 +1,27 @@
 ---
 name: code-review
-description: Use when reviewing PRs or before opening a PR – API design, null-safety, exceptions, backward compatibility, dependencies, security, and test quality
+description: Use when reviewing PRs for contentstack-android—API stability, Gradle, tests, and mobile security.
 ---
 
-# Code Review – Contentstack Android CDA SDK
-
-Use this skill when performing or preparing a pull request review for the Android CDA SDK. Aligns with the Java CDA SDK review bar.
+# Code review – contentstack-android
 
 ## When to use
 
-- Reviewing someone else’s PR.
-- Self-reviewing your own PR before submission.
-- Checking that changes meet project standards (API, errors, compatibility, tests, security).
+- Reviewing feature or fix PRs for the Android SDK
+- Auditing dependency or manifest changes
 
 ## Instructions
 
-Work through the checklist below. Optionally tag items with severity: **Blocker**, **Major**, **Minor**.
-
-### 1. API design and stability
-
-- [ ] **Public API:** New or changed public methods/classes are necessary and documented (Javadoc with purpose and, where relevant, params/returns).
-- [ ] **Backward compatibility:** No breaking changes to public API unless explicitly agreed (e.g. major version). Deprecations should have alternatives and timeline.
-- [ ] **Naming:** Consistent with existing SDK style and CDA terminology (e.g. `Stack`, `Entry`, `Query`, `Config`).
-
-**Severity:** Breaking public API without approval = Blocker. Missing docs on new public API = Major.
-
-### 2. Error handling and robustness
-
-- [ ] **Errors:** API failures are mapped to the SDK `Error` type and passed through existing callback/result patterns (e.g. `ResultCallBack`).
-- [ ] **Null safety:** No unintended NPEs; document or validate parameters for public API where it matters.
-- [ ] **Exceptions:** Checked exceptions are handled or declared; use of unchecked exceptions is intentional and documented where relevant.
-
-**Severity:** Wrong or missing error handling in new code = Major.
-
-### 3. Dependencies and security
-
-- [ ] **Dependencies:** New or upgraded dependencies are justified. Version bumps are intentional and do not introduce known vulnerabilities.
-- [ ] **SCA:** Any security findings (e.g. Snyk, Dependabot) in the change set are addressed or explicitly deferred with a ticket.
-
-**Severity:** New critical/high vulnerability = Blocker.
-
-### 4. Testing
-
-- [ ] **Coverage:** New or modified behavior has corresponding unit and/or instrumented tests.
-- [ ] **Conventions:** Tests follow naming (`Test*` for unit tests) and live in `src/test/` or `src/androidTest/` as appropriate.
-- [ ] **Quality:** Tests are readable, deterministic (no flakiness), and assert meaningful behavior.
-
-**Severity:** No tests for new behavior = Blocker. Flaky or weak tests = Major.
-
-### 5. Optional severity summary
+### Checklist
 
-- **Blocker:** Must fix before merge (e.g. breaking API without approval, security issue, no tests for new code).
-- **Major:** Should fix (e.g. inconsistent error handling, missing Javadoc on new public API, flaky tests).
-- **Minor:** Nice to fix (e.g. style, minor docs, redundant code).
+- **API**: Public SDK surface changes justified and documented.
+- **Gradle**: Version bumps coherent; no accidental signing or secret commits.
+- **Tests**: Unit tests for new logic; consider Robolectric limitations.
+- **Manifest/resources**: No unnecessary permissions; ProGuard rules updated if needed.
+- **Cross-SDK**: Behavior consistent with Java/Swift where applicable.
 
-## References
+### Severity hints
 
-- Project rule: `.cursor/rules/code-review.mdc`
-- Testing skill: `skills/testing/SKILL.md` for test standards
+- **Blocker**: Broken `:contentstack:testDebugUnitTest`, leaked credentials, or broken publish metadata.
+- **Major**: Missing coverage for risky network or caching changes.
+- **Minor**: Formatting, comments, internal refactors.

skills/contentstack-android-cda/SKILL.md

@@ -1,53 +1,25 @@
 ---
 name: contentstack-android-cda
-description: Use when implementing or changing CDA features – Stack/Config, entries, assets, sync, HTTP, callbacks, and Content Delivery API alignment
+description: Use for the public Android Content Delivery SDK surface and package com.contentstack.sdk.
 ---
 
-# Contentstack Android CDA SDK – CDA Implementation
-
-Use this skill when implementing or changing Content Delivery API (CDA) behavior in the Android SDK.
+# Android CDA SDK – contentstack-android
 
 ## When to use
 
-- Adding or modifying Stack, Entry, Query, Asset, Content Type, or Sync behavior.
-- Changing Config options (host, version, region, branch, proxy, connection pool).
-- Working with the HTTP layer (CSHttpConnection/Volley, Stack/APIService/Retrofit/OkHttp) or callbacks and Error handling.
+- Changing SDK entry points consumed by Android apps
+- Working with stack configuration, entries, or HTTP client usage in this module
 
 ## Instructions
 
-### Stack and Config
-
-- **Entry point:** `Contentstack.stack(Context, apiKey, deliveryToken, environment)`. Overloads accept `Config` for host, version, region, branch, proxy, connection pool, endpoint.
-- **Defaults:** host `cdn.contentstack.io`, version `v3` (see `Config`). Region and branch via `Config.setRegion()`, `Config.setBranch()`.
-- **Reference:** `Contentstack.java`, `Stack.java`, `Config.java`.
-
-### CDA resources
-
-- **Entries:** `Stack.contentType(uid).entry(uid)`, query APIs, and entry fetch. Use existing `Entry`, `Query`, `EntriesModel`, and callback types.
-- **Assets:** `Stack.assetLibrary()`, asset fetch and query. Use `Asset`, `AssetLibrary`, `AssetModel`, and related callbacks.
-- **Content types:** Content type schema and listing. Use `ContentType`, `ContentTypesModel`, `ContentTypesCallback`.
-- **Sync:** Sync API usage. Use existing sync request/response and pagination patterns.
-- **Official API:** Align with [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) for parameters, response shape, and semantics.
-
-### HTTP and retry
-
-- **HTTP:** CDA requests use **CSHttpConnection** (Volley) and/or **Retrofit** + **OkHttp** (e.g. `Stack`, `APIService`). Set headers (User-Agent, auth) per constants and existing request building.
-- **Retry:** Volley retry is configured via `DefaultRetryPolicy` in `CSHttpConnection`; constants in `SDKConstant` (e.g. `TimeOutDuration`, `NumRetry`, `BackOFMultiplier`). Keep timeouts and retry behavior consistent when changing the HTTP layer.
-- **Reference:** `CSHttpConnection.java`, `CSConnectionRequest.java`, `Stack.java`, `APIService.java`, `SDKConstant.java`.
-
-### Errors and callbacks
+### Module
 
-- **Errors:** Map API errors to the `Error` class. Pass to the appropriate callback (e.g. `ResultCallBack`) so callers receive a consistent error shape.
-- **Callbacks:** Use existing callback types (`ResultCallBack`, `EntryResultCallBack`, `QueryResultsCallBack`, etc.). Do not change callback contracts without considering backward compatibility.
+- Primary code lives in **`contentstack/`** with namespace **`com.contentstack.sdk`** (`android { namespace ... }`).
 
-## Key classes
+### API design
 
-- **Entry points:** `Contentstack`, `Stack`, `Config`
-- **CDA:** `Entry`, `Query`, `Asset`, `AssetLibrary`, `ContentType`, sync-related classes
-- **HTTP:** `CSHttpConnection`, `CSConnectionRequest`, `APIService`, `Stack` (Retrofit)
-- **Errors / results:** `Error`, `QueryResult`, and callback interfaces in `com.contentstack.sdk`
+- Keep public Java/Kotlin APIs stable for app developers—use semver for breaking changes in published AARs.
 
-## References
+### Integration
 
-- [Content Delivery API – Contentstack Docs](https://www.contentstack.com/docs/apis/content-delivery-api/)
-- Project rules: `.cursor/rules/contentstack-android-cda.mdc`, `.cursor/rules/java.mdc`
+- Behavior should stay aligned with other CDA SDKs where features overlap (queries, preview, etc.)—check parity with Java/Swift docs when adding features.

skills/dev-workflow/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: dev-workflow
+description: Use for Gradle tasks, CI, release publishing, and branch flow in contentstack-android.
+---
+
+# Development workflow – contentstack-android
+
+## When to use
+
+- Running local builds/tests before a PR
+- Aligning with GitHub Actions (branch checks, SCA, publish)
+
+## Instructions
+
+### Project shape
+
+- Root project **`contentstack-android`** includes module **`:contentstack`** (`settings.gradle`).
+
+### Commands
+
+- From repo root: `./gradlew :contentstack:testDebugUnitTest` for JVM unit tests on the library.
+- Use `./gradlew clean` when switching branches or after AGP/cache issues.
+
+### CI
+
+- Workflows under `.github/workflows/` enforce policies and may publish artifacts—coordinate version bumps with `contentstack/build.gradle` `PUBLISH_*` fields.

skills/framework/SKILL.md

@@ -1,52 +1,25 @@
 ---
 name: framework
-description: Use when touching config or HTTP layer – Config, CSHttpConnection (Volley), Stack/APIService (Retrofit/OkHttp), timeouts, retry, and error handling
+description: Use for AGP, Gradle plugins, JaCoCo, signing, and native Android build concerns in contentstack-android.
 ---
 
-# Framework – Contentstack Android CDA SDK
-
-Use this skill when changing configuration or the HTTP connection layer (Volley and/or Retrofit/OkHttp).
+# Build & platform – contentstack-android
 
 ## When to use
 
-- Modifying **Config** options (host, version, region, branch, proxy, connection pool, endpoint).
-- Changing **CSHttpConnection** (Volley), request building, or **Stack**’s Retrofit/OkHttp setup.
-- Changing retry/timeout constants (e.g. `SDKConstant.TimeOutDuration`, `NumRetry`, `BackOFMultiplier`) or `DefaultRetryPolicy` usage.
-- Introducing or changing connection pooling, timeouts, or interceptors.
+- Upgrading Android Gradle Plugin, compile SDK, or dependencies
+- Fixing signing, packaging excludes, or multidex issues
 
 ## Instructions
 
-### Config
-
-- **Config** holds: host (default `cdn.contentstack.io`), version (default `v3`), environment, branch, region (`ContentstackRegion`), proxy, connection pool, endpoint, earlyAccess.
-- Use setter-style APIs (e.g. `setHost`, `setBranch`, `setRegion`). Preserve default values where existing behavior depends on them.
-- **Reference:** `contentstack/src/main/java/com/contentstack/sdk/Config.java`.
-
-### Volley and CSHttpConnection
-
-- **CSHttpConnection** uses **Volley** to execute requests. It is invoked via **CSConnectionRequest**; responses and errors are passed to the request’s callback (e.g. `onRequestFinished`).
-- **Retry:** Volley’s `DefaultRetryPolicy` is used in `CSHttpConnection` with constants from **SDKConstant** (e.g. `TimeOutDuration`, `NumRetry`, `BackOFMultiplier`). Keep retry/timeout behavior consistent when changing this path.
-- **Reference:** `CSHttpConnection.java`, `CSConnectionRequest.java`, `IRequestModelHTTP.java`, `SDKConstant.java`.
-
-### Stack, Retrofit, and OkHttp
-
-- **Stack** builds an **OkHttpClient** and **Retrofit** instance and uses **APIService** for certain CDA calls (e.g. taxonomy). Base URL and headers are derived from Config/stack state.
-- Do not bypass the shared client/Config when adding new CDA calls that use Retrofit.
-- **Reference:** `Stack.java`, `APIService.java`.
-
-### Error handling
+### Gradle
 
-- Map HTTP and API errors to the **Error** class. Pass errors through the same callback mechanism used elsewhere so callers get a consistent contract.
-- **Reference:** `Error.java`, and callback interfaces that receive errors.
+- Root **`build.gradle`** pins AGP and Nexus publish plugin versions; module plugin **`com.android.library`** applies in `contentstack/build.gradle`.
 
-## Key classes
+### Publishing
 
-- **Config:** `Config.java`, `ContentstackRegion`
-- **Volley path:** `CSHttpConnection.java`, `CSConnectionRequest.java`, `IRequestModelHTTP.java`, `SDKConstant.java`
-- **Retrofit path:** `Stack.java`, `APIService.java`
-- **Errors/callbacks:** `Error.java`, `ResultCallBack`, and related callback types
+- Maven coordinates use `PUBLISH_GROUP_ID`, `PUBLISH_ARTIFACT_ID`, `PUBLISH_VERSION`—bump with releases.
 
-## References
+### Keystore
 
-- Project rules: `.cursor/rules/contentstack-android-cda.mdc`, `.cursor/rules/java.mdc`
-- CDA skill: `skills/contentstack-android-cda/SKILL.md` for CDA-specific usage of Config and HTTP
+- Debug/release signing references **`key.keystore`** in the module—suitable for sample/debug only; production signing is consumer responsibility.