Updated cursor rules as per new structure

Author: sunil-lakshman

.cursor/rules/README.md

@@ -1,37 +1,5 @@
-# Cursor Rules — `contentstack-management`
+# Cursor (optional)
 
-Rules for **contentstack-management-python**: Python **CMA** SDK (`contentstack_management`).
+**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool).
 
-## Rules overview
-
-| Rule | Role |
-|------|------|
-| [`dev-workflow.md`](dev-workflow.md) | Branch/PR, install, pytest (`unit` / `api` / `mock`), tooling |
-| [`python.mdc`](python.mdc) | Python conventions, `contentstack_management/`, `setup.py` |
-| [`contentstack-management-python.mdc`](contentstack-management-python.mdc) | **Client**, **Stack**, **`_APIClient`**, CMA modules |
-| [`testing.mdc`](testing.mdc) | pytest suites, **`tests/cred.py`**, env |
-| [`code-review.mdc`](code-review.mdc) | PR checklist (**always applied**) |
-
-## Rule application
-
-| Context | Typical rules |
-|---------|----------------|
-| **Every session** | `code-review.mdc` |
-| **Most repo files** | `dev-workflow.md` |
-| **`contentstack_management/`** | `python.mdc` + `contentstack-management-python.mdc` |
-| **`tests/**`** | `testing.mdc` |
-| **Packaging / CI** | `python.mdc` |
-
-## Quick reference
-
-| File | `alwaysApply` | Globs (summary) |
-|------|---------------|-----------------|
-| `dev-workflow.md` | no | `**/*.py`, `setup.py`, `requirements.txt`, `.github/**/*.yml` |
-| `python.mdc` | no | `contentstack_management/**/*.py`, `setup.py`, `requirements.txt` |
-| `contentstack-management-python.mdc` | no | `contentstack_management/**/*.py` |
-| `testing.mdc` | no | `tests/**/*.py` |
-| `code-review.mdc` | **yes** | — |
-
-## Skills
-
-- [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)
+This folder only points contributors here so nothing editor-specific duplicates the canonical docs.

.cursor/rules/code-review.mdc

@@ -1,6 +1,8 @@
-# AGENTS.md — AI / automation context
+# Contentstack Management Python — Agent guide
 
-## Project
+**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
 
 | | |
 |---|---|
@@ -29,7 +31,7 @@
 | `contentstack_management/__init__.py` | Public exports |
 | `tests/cred.py` | **`get_credentials()`** — **dotenv** + env vars for API/mock tests |
 
-## Common commands
+## Commands (quick reference)
 
 ```bash
 pip install -e ".[dev]"
@@ -48,9 +50,23 @@ Loaded via **`tests/cred.py`** (`load_dotenv()`). Examples include **`HOST`**, *
 
 Do not commit secrets.
 
-## Further guidance
+## 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
 
-- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
-- **Skills:** [`skills/README.md`](skills/README.md)
+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/).

.cursor/rules/contentstack-management-python.mdc

@@ -1,10 +1,19 @@
-# Project skills — `contentstack-management`
+# Skills — Contentstack Management Python
 
-| Skill | When to use |
-|-------|-------------|
-| [`code-review/`](code-review/SKILL.md) | PR review, semver, Client / HTTP changes |
-| [`testing/`](testing/SKILL.md) | Unit vs API vs mock pytest |
-| [`contentstack-management-python/`](contentstack-management-python/SKILL.md) | **Client**, **Stack**, **`_APIClient`**, CMA modules |
-| [`framework/`](framework/SKILL.md) | **`requests`** + **`_APIClient`** + OAuth interceptor |
+**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`).
 
-**Overview:** [`AGENTS.md`](../AGENTS.md) · **Rules:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)
+## 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.

.cursor/rules/testing.mdc

@@ -1,19 +1,50 @@
 ---
 name: code-review
-description: PR review for contentstack-management — public API, Client, _APIClient, OAuth, tests.
+description: PR checklist—public API, Client/Stack, _APIClient/OAuth, tests, secrets; align with README and exports.
 ---
 
-# Code review — `contentstack-management`
+# Code review — Contentstack Management Python
 
-## Checklist
+## When to use
 
-- [ ] **API:** New or changed **`Client`** / **Stack** / resource methods documented; **`contentstack_management/__init__.py`** exports updated if public surface changes.
-- [ ] **Version:** **`__version__`** in **`contentstack_management/__init__.py`** aligned with release strategy when user-visible behavior changes.
-- [ ] **HTTP:** **`_APIClient`** or OAuth changes covered by unit tests; retries and headers remain consistent.
-- [ ] **Tests:** **`pytest tests/unit/`** passes; extend **`tests/api`** or **`tests/mock`** when integration or contract behavior changes.
-- [ ] **Secrets:** No tokens in repo; use **`tests/cred.py`** / env for local API runs.
+- 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
 
-- `.cursor/rules/code-review.mdc`
-- `.cursor/rules/dev-workflow.md`
+- **`skills/testing/SKILL.md`**
+- **`skills/contentstack-management/SKILL.md`**
+- **`skills/dev-workflow/SKILL.md`**

AGENTS.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/README.md

@@ -1,14 +1,14 @@
 ---
-description: "Branches, install, and test layout for contentstack-management-python"
-globs:
-  - "**/*.py"
-  - "setup.py"
-  - "requirements.txt"
-  - ".github/**/*.yml"
-alwaysApply: false
+name: dev-workflow
+description: Install, pytest unit/API/mock, versioning, pylint, hooks—standard workflow for this SDK repo.
 ---
 
-# Development workflow — `contentstack-management`
+# 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
 
@@ -26,6 +26,14 @@ alwaysApply: false
 - **pylint** is listed in **`requirements.txt`**; follow existing style in touched files.
 - **Husky / Talisman / Snyk** — see **README.md** for local hook setup.
 
-## Links
+## 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`](../../AGENTS.md) · [`skills/contentstack-management-python/SKILL.md`](../../skills/contentstack-management-python/SKILL.md)
+- **`AGENTS.md`**
+- **`skills/contentstack-management/SKILL.md`**
+- **`skills/testing/SKILL.md`**