Enh: Added cursor rules and skills

.cursor/rules/README.md

@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool).
+
+This folder only points contributors here so nothing editor-specific duplicates the canonical docs.

AGENTS.md

@@ -0,0 +1,72 @@
+# Contentstack Management Python — Agent guide
+
+**Universal entry point** for anyone automating or assisting work in this repo—AI agents (Cursor, Copilot, CLI tools), reviewers, and contributors. Conventions and detailed guidance live in **`skills/*/SKILL.md`**, not in editor-specific config, so the same instructions apply whether or not you use Cursor.
+
+## What this repo is
+
+| | |
+|---|---|
+| **Name** | **`contentstack-management`** (PyPI) — **Contentstack Management Python SDK** |
+| **Purpose** | Python client for the **Content Management API (CMA)**: organizations, stacks, content types, entries, assets, webhooks, workflows, OAuth, and related resources. Uses **`requests`** via **`_APIClient`**. |
+| **Repository** | [contentstack/contentstack-management-python](https://github.com/contentstack/contentstack-management-python.git) |
+
+## Tech stack
+
+| Area | Details |
+|------|---------|
+| **Language** | **Python** ≥ 3.9 (`setup.py` `python_requires`) |
+| **HTTP** | **`requests`**, **`requests-toolbelt`**, **`urllib3`** |
+| **Tests** | **pytest** — **`tests/unit`**, **`tests/api`**, **`tests/mock`** |
+| **Lint** | **pylint** (see `requirements.txt`) |
+| **Secrets / hooks** | **Talisman**, **Snyk** (see **README.md** development setup) |
+
+## Source layout
+
+| Path | Role |
+|------|------|
+| `contentstack_management/contentstack.py` | **`Client`**, **`Region`**, endpoint construction, **`user_agents`**, optional **OAuth** wiring |
+| `contentstack_management/_api_client.py` | **`_APIClient`** — HTTP calls, retries, optional **OAuth** interceptor |
+| `contentstack_management/stack/stack.py` | **Stack**-scoped CMA operations |
+| `contentstack_management/*/` | Domain modules (entries, assets, webhooks, taxonomies, …) |
+| `contentstack_management/__init__.py` | Public exports |
+| `tests/cred.py` | **`get_credentials()`** — **dotenv** + env vars for API/mock tests |
+
+## Commands (quick reference)
+
+```bash
+pip install -e ".[dev]"
+# or: pip install -r requirements.txt && pip install pytest pytest-cov
+
+pytest tests/unit/ -v
+pytest tests/api/ -v      # live CMA — needs .env (see tests/cred.py)
+pytest tests/mock/ -v
+pytest tests/ -v
+coverage run -m pytest tests/unit/
+```
+
+## Environment variables (API / integration tests)
+
+Loaded via **`tests/cred.py`** (`load_dotenv()`). Examples include **`HOST`**, **`APIKEY`**, **`AUTHTOKEN`**, **`MANAGEMENT_TOKEN`**, **`ORG_UID`**, and resource UIDs (**`CONTENT_TYPE_UID`**, **`ENTRY_UID`**, …). See that file for the full list.
+
+Do not commit secrets.
+
+## Where the real documentation lives: skills
+
+Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review:
+
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Install, pytest suites, packaging version, pylint, hooks, PR baseline |
+| **Contentstack Management (SDK)** | [`skills/contentstack-management/SKILL.md`](skills/contentstack-management/SKILL.md) | **`Client`**, **`Stack`**, **`_APIClient`**, CMA resources, OAuth, CMA docs |
+| **Python style & repo layout** | [`skills/python-style/SKILL.md`](skills/python-style/SKILL.md) | Package layout, naming, imports via **`_APIClient`**, secrets in logs |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | pytest unit / API / mock, **`tests/cred.py`**, env hygiene |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist—public API, HTTP/auth, tests, security |
+| **Framework / HTTP** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | **`requests`**, retries, OAuth interceptor, where to change transport |
+
+An index with short “when to use” hints is in [`skills/README.md`](skills/README.md).
+
+## Using Cursor
+
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same source of truth as everyone else; no separate `.mdc` rule files.
+
+Product docs: [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/).

skills/README.md

@@ -0,0 +1,19 @@
+# Skills — Contentstack Management Python
+
+**This directory is the source of truth** for conventions (workflow, SDK API, style, tests, review, HTTP layer). Read **`AGENTS.md`** at the repo root for the index and quick commands; each skill is a folder with **`SKILL.md`** (YAML frontmatter: `name`, `description`).
+
+## When to use which skill
+
+| Skill folder | Use when |
+|--------------|----------|
+| **dev-workflow** | Install, **`pytest`** (unit / API / mock), **`__version__`**, pylint, Talisman/Snyk, before PR |
+| **contentstack-management** | **`Client`**, **`Stack`**, **`_APIClient`**, domain modules, OAuth, CMA paths and payloads |
+| **python-style** | Editing **`contentstack_management/`** or **`setup.py`** / **`requirements.txt`**—layout, style, imports |
+| **testing** | Adding or changing tests under **`tests/`**, **`tests/cred.py`**, env for API runs |
+| **code-review** | PR checklist, API semver, HTTP regressions, secrets |
+| **framework** | Changing **`_APIClient`**, retries, **`requests`** usage, OAuth interceptor wiring |
+
+## How to use these docs
+
+- **Humans / any AI tool:** Start at **`AGENTS.md`**, then open the relevant **`skills/<name>/SKILL.md`**.
+- **Cursor users:** **`.cursor/rules/README.md`** only points to **`AGENTS.md`** so guidance stays universal—no duplicate `.mdc` rule sets.

skills/code-review/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: code-review
+description: PR checklist—public API, Client/Stack, _APIClient/OAuth, tests, secrets; align with README and exports.
+---
+
+# Code review — Contentstack Management Python
+
+## When to use
+
+- Reviewing a PR, self-review before submit, or automated review prompts.
+
+## Instructions
+
+Work through the checklist below. Optionally tag findings: **Blocker**, **Major**, **Minor**.
+
+### Public API
+
+- [ ] **Exported** **`Client`**, **`Region`**, stack and resource helpers match **README** and **`contentstack_management.__all__`** / **`__init__.py`**.
+- [ ] **Docstrings** on **`Client`** and changed public methods when behavior or parameters change.
+
+### Compatibility
+
+- [ ] Avoid breaking **`Client`** constructor or stack method chains without a semver strategy; document migration for breaking changes.
+
+### HTTP / auth
+
+- [ ] Changes to **`_APIClient`** or **OAuth** paths: verify retries, headers, and interceptor behavior with unit tests; no regressions for **authtoken** / **management_token** headers.
+
+### Testing
+
+- [ ] **Unit** coverage for new logic; **API** updates when live CMA request/response behavior changes; **mock** when contract-style tests are appropriate.
+- [ ] **`pytest tests/unit/`** passes.
+
+### Security
+
+- [ ] No hardcoded tokens; no logging secrets in new code.
+
+### Severity (optional)
+
+| Level | Examples |
+|-------|----------|
+| **Blocker** | Breaking public API without approval; security issue; no tests for new logic where tests are practical |
+| **Major** | Inconsistent HTTP/auth behavior; README examples that do not match code |
+| **Minor** | Style; minor docs |
+
+## References
+
+- **`skills/testing/SKILL.md`**
+- **`skills/contentstack-management/SKILL.md`**
+- **`skills/dev-workflow/SKILL.md`**

skills/contentstack-management/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: contentstack-management
+description: Public CMA surface—Client, Stack, _APIClient, domain resources, OAuth; align with CMA docs and semver.
+---
+
+# Contentstack Management — SDK skill
+
+## When to use
+
+- Implementing or changing **`Client`**, **Stack**, or resource modules (entries, assets, webhooks, …).
+- Updating **`README.md`** or public exports for user-visible behavior.
+- Assessing semver impact of constructor, method, or export changes.
+
+## Main entry (consumer API)
+
+- **`contentstack_management.Client`** in **`contentstack.py`**: builds CMA **endpoint** from **region** / **host** / **scheme**, merges **headers** (**authtoken**, **management_token**, **early_access**), constructs **`_APIClient`**, optional **`oauth_config`** with **`OAuthHandler`**.
+
+## Structure
+
+- **`Stack`** — **`contentstack_management/stack/stack.py`**: stack-scoped resources (content types, entries, assets, branches, webhooks, …).
+- **Org / user** — **`organizations/`**, **`users/`**, **`user_session/`** as applicable.
+- **Resources** — packages under **`contentstack_management/`** following existing patterns.
+- **OAuth** — **`oauth/oauth_handler.py`**, **`oauth/oauth_interceptor.py`**; keep aligned with **`_APIClient`** request path.
+
+## HTTP layer
+
+- **`_APIClient._call_request`** — central place for method, URL, JSON, files; respect **timeout** and **max_retries**.
+
+## Extending
+
+- Add methods on the appropriate resource class; align path and payload shapes with **CMA** docs.
+- Prefer routing HTTP through **`_APIClient`** for consistent retries and OAuth handling.
+
+## Docs and versioning
+
+- Exported **`Client`**, **`Region`**, and stack helpers should match **README** and **`contentstack_management.__init__.py`**.
+- Document migration for intentional breaking changes.
+
+## References
+
+- [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/)
+- **`skills/framework/SKILL.md`**
+- **`skills/python-style/SKILL.md`**

skills/dev-workflow/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: dev-workflow
+description: Install, pytest unit/API/mock, versioning, pylint, hooks—standard workflow for this SDK repo.
+---
+
+# Development workflow — Contentstack Management Python
+
+## When to use
+
+- Setting up locally, opening a PR, or matching CI expectations.
+- Answering “how do we run tests?” or “what runs in CI?”
+
+## Before a PR
+
+1. **Install** — `pip install -e ".[dev]"` or install **`requirements.txt`** plus **pytest** / **pytest-cov** as needed.
+2. **`pytest tests/unit/`** — required baseline (matches CI **`coverage run -m pytest tests/unit/`**).
+3. **API tests** — `pytest tests/api/` when your change affects live CMA behavior; configure **`.env`** per **`tests/cred.py`**. Never commit tokens.
+4. **Mock tests** — `pytest tests/mock/` when extending mocked HTTP or fixtures.
+
+## Packaging
+
+- Bump **`contentstack_management/__init__.py`** **`__version__`** and align **`setup.py`** versioning if release-facing.
+
+## Tooling
+
+- **pylint** is listed in **`requirements.txt`**; follow existing style in touched files.
+- **Husky / Talisman / Snyk** — see **README.md** for local hook setup.
+
+## Pull requests
+
+- Build passes: **`pytest tests/unit/`** at minimum; run **API** / **mock** when your change touches those layers.
+- Follow **`skills/code-review/SKILL.md`** before merge.
+- Prefer backward-compatible public API; call out breaking changes and semver.
+
+## References
+
+- **`AGENTS.md`**
+- **`skills/contentstack-management/SKILL.md`**
+- **`skills/testing/SKILL.md`**

skills/framework/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: framework
+description: requests-based _APIClient, retries, timeout, OAuth interceptor—central HTTP for the Management SDK.
+---
+
+# Framework / HTTP — Contentstack Management Python
+
+## When to use
+
+- Editing **`contentstack_management/_api_client.py`** or OAuth interceptor/handler wiring.
+- Changing retry policy, timeouts, or how **`requests`** is invoked.
+
+## Integration point
+
+- **`_APIClient`** uses **`requests`** in **`_call_request`**, honors **timeout** and **max_retries**, and delegates to **`oauth_interceptor`** when configured.
+
+## When to change
+
+- **Retry or transport behavior** — keep logic centralized in **`_APIClient`** unless a resource truly needs a documented exception.
+- **Auth headers** — prefer extending **`Client`** / **`user_agents`** patterns rather than scattering header merges.
+
+## Testing
+
+- **Unit** — mock **`requests`** or **`_APIClient`** at the boundary used by existing tests.
+- **API** — full stack via credentials from **`tests/cred.py`**.
+
+## References
+
+- **`skills/contentstack-management/SKILL.md`**
+- **`skills/dev-workflow/SKILL.md`**
+- **`skills/testing/SKILL.md`**

skills/python-style/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: python-style
+description: Package layout under contentstack_management/, setup.py, pylint-friendly style, imports, no secret logging.
+---
+
+# Python style and repo layout — Contentstack Management Python
+
+## When to use
+
+- Editing any Python under **`contentstack_management/`**, **`setup.py`**, or **`requirements.txt`**.
+- Adding modules or changing how the public package surface is exported.
+
+## Layout
+
+- **`contentstack_management/contentstack.py`** — **`Client`**, **`Region`**, **`user_agents`**, OAuth wiring.
+- **`contentstack_management/_api_client.py`** — **`_APIClient`** (HTTP, retries).
+- **`contentstack_management/stack/`** — stack-scoped API surface.
+- **Domain modules** — **`entries/`**, **`assets/`**, **`webhooks/`**, **`oauth/`**, etc.
+
+## Style
+
+- Match existing modules: naming, docstrings, and patterns already used in the same directory.
+- Prefer small, focused changes; keep **`__init__.py`** exports consistent with public API intent (**`README`**, **`contentstack_management.__all__`**).
+
+## Imports
+
+- Use **`requests`** (and **`requests-toolbelt`** where already used) through **`_APIClient`** patterns rather than ad-hoc clients in domain modules unless justified.
+
+## Security
+
+- Do not log **authtokens**, **management tokens**, **passwords**, or **API keys**; preserve existing header handling in **`Client`**.
+
+## References
+
+- **`skills/framework/SKILL.md`**
+- **`skills/contentstack-management/SKILL.md`**
+- **`skills/testing/SKILL.md`**

skills/testing/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: testing
+description: pytest—unit, API, mock; tests/cred.py and .env; no committed secrets.
+---
+
+# Testing — Contentstack Management Python
+
+## When to use
+
+- Adding or changing tests under **`tests/`**.
+- Debugging API vs mock failures; improving **`tests/cred.py`** usage.
+
+## Runner and tooling
+
+| Suite | Path | Notes |
+|-------|------|--------|
+| **Unit** | `tests/unit/**` | Fast, isolated; primary CI target |
+| **API** | `tests/api/**` | Live CMA — **`.env`** via **`tests/cred.py`** |
+| **Mock** | `tests/mock/**` | Mocked HTTP / contracts |
+
+### Commands
+
+| Goal | Command |
+|------|---------|
+| Unit (CI-style) | `pytest tests/unit/ -v` or `coverage run -m pytest tests/unit/` |
+| API (live CMA) | `pytest tests/api/ -v` |
+| Mock | `pytest tests/mock/ -v` |
+| Full tree | `pytest tests/ -v` |
+
+## Environment (`tests/cred.py`)
+
+- **`get_credentials()`** loads **dotenv** and returns host, tokens, and resource UIDs.
+- Common vars: **`HOST`**, **`APIKEY`**, **`AUTHTOKEN`**, **`MANAGEMENT_TOKEN`**, **`ORG_UID`**, plus resource UIDs as tests require.
+- Use a **`.env`** at repo root for local API runs; never commit secrets.
+
+## Hygiene
+
+- No committed secrets; use placeholders or env-only values for CI.
+- Avoid leaving **`pytest.skip`** or focused-only tests enabled in paths meant for full suite runs unless intentional.
+
+## References
+
+- **`skills/dev-workflow/SKILL.md`**
+- **`skills/code-review/SKILL.md`**