Updated cusrsor rules structure

Author: sunil-lakshman

.cursor/rules/README.md

@@ -1,37 +1,5 @@
-# Cursor Rules — `contentstack_utils`
+# Cursor (optional)
 
-Rules for **contentstack-utils-python**: Python **utils** package for **RTE / embedded** rendering, **GQL**, and **editable tags** (companion to the Contentstack Python SDK).
+**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, venv, **pytest**, lint (**ruff** / **black** / **flake8**) |
-| [`python.mdc`](python.mdc) | Python layout, `contentstack_utils/`, `setup.py` |
-| [`contentstack-utils-python.mdc`](contentstack-utils-python.mdc) | **Utils**, **Options**, RTE/embedded, **GQL**, **entry_editable** |
-| [`testing.mdc`](testing.mdc) | **pytest** under **`tests/`** |
-| [`code-review.mdc`](code-review.mdc) | PR checklist (**always applied**) |
-
-## Rule application
-
-| Context | Typical rules |
-|---------|----------------|
-| **Every session** | `code-review.mdc` |
-| **Most files** | `dev-workflow.md` |
-| **`contentstack_utils/`** | `python.mdc` + `contentstack-utils-python.mdc` |
-| **`tests/**`** | `testing.mdc` |
-| **`setup.py` / packaging** | `python.mdc` |
-
-## Quick reference
-
-| File | `alwaysApply` | Globs (summary) |
-|------|---------------|-----------------|
-| `dev-workflow.md` | no | `**/*.py`, `requirements.txt`, `setup.py` |
-| `python.mdc` | no | `contentstack_utils/**/*.py`, `setup.py` |
-| `contentstack-utils-python.mdc` | no | `contentstack_utils/**/*.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,14 +1,14 @@
-# AGENTS.md — AI / automation context
+# Contentstack Utils 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.
 
-| | |
-|---|---|
-| **Name** | **`contentstack_utils`** (PyPI) — **Contentstack Python Utils SDK** |
-| **Purpose** | Utilities for **Contentstack** headless CMS: **RTE / embedded** rendering (`Utils`, `Options`), **GQL** helpers, **editable tags** on entries, HTML/metadata helpers. Often used alongside the **`Contentstack`** Python delivery package. |
-| **Repository** | [contentstack/contentstack-utils-python](https://github.com/contentstack/contentstack-utils-python.git) |
+## What this repo is
 
-## Tech stack
+- **Name:** [contentstack-utils-python](https://github.com/contentstack/contentstack-utils-python) — **`contentstack_utils`** on PyPI (**Contentstack Python Utils SDK**).
+- **Purpose:** Utilities for **Contentstack** headless CMS: **RTE / embedded** rendering (`Utils`, `Options`), **GQL** helpers, **editable tags** on entries, HTML/metadata helpers. Often used alongside the **Contentstack** Python delivery package.
+- **Out of scope:** This package does **not** ship HTTP clients or stack credentials. Apps fetch content with the [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) / Python SDK, then pass field data into **`Utils`**.
+
+## Tech stack (at a glance)
 
 | Area | Details |
 |------|---------|
@@ -32,7 +32,7 @@
 | `contentstack_utils/__init__.py` | Public exports — keep **`__all__`** aligned with documented API |
 | `tests/` | pytest modules (`test_*.py`), mocks under `tests/mocks/` |
 
-## Common commands
+## Commands (quick reference)
 
 ```bash
 python -m venv .venv && source .venv/bin/activate  # or equivalent on Windows
@@ -47,9 +47,21 @@ coverage run -m pytest && coverage report -m
 
 - Do not commit **API keys**, **delivery tokens**, or other secrets. Examples in **`README.md`** use placeholders only.
 
-## 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) | Branches, CI, venv, **pytest**, ruff/black/flake8, PR expectations |
+| **Contentstack Utils (SDK)** | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | **`Utils`**, **`Options`**, RTE/embedded, **GQL**, editable tags, JS parity, semver |
+| **Python style & layout** | [`skills/python-style/SKILL.md`](skills/python-style/SKILL.md) | Package layout, typing, imports, **`lxml`**, **`setup.py`**, security |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | **pytest** layout, coverage, **`tests/mocks/`**, hygiene |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist (API, **`__all__`**, deps, tests, secrets) |
+| **Framework / integration** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | **`lxml`**, companion **Contentstack** Python SDK, dependency boundaries |
+
+An index with short “when to use” hints is in [`skills/README.md`](skills/README.md).
 
-- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
-- **Skills:** [`skills/README.md`](skills/README.md)
+## Using Cursor
 
-Product docs: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
+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.

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

@@ -1,10 +1,19 @@
-# Project skills — `contentstack_utils`
+# Skills – Contentstack Utils Python
 
-| Skill | When to use |
-|-------|-------------|
-| [`code-review/`](code-review/SKILL.md) | PR review, semver, public **`__all__`**, dependency changes |
-| [`testing/`](testing/SKILL.md) | **pytest**, coverage, **`tests/mocks`** |
-| [`contentstack-utils-python/`](contentstack-utils-python/SKILL.md) | **`Utils`**, **`Options`**, RTE/embedded, **GQL**, editable tags |
-| [`framework/`](framework/SKILL.md) | **`lxml`**, companion **`Contentstack`** Python SDK usage |
+**This directory is the source of truth** for conventions (workflow, SDK API, style, tests, review, framework). 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** | Branches, CI, venv, **`pip install -e .`**, **pytest**, ruff/black/flake8, PRs |
+| **contentstack-utils** | **`Utils`**, **`Options`**, RTE/embedded, **GQL**, editable tags, semver, README |
+| **python-style** | `contentstack_utils/` layout, typing, **`lxml`** usage, **`setup.py`** |
+| **testing** | **pytest**, coverage, **`tests/mocks/`**, HTML reports |
+| **code-review** | PR checklist, public API / **`__all__`**, dependencies, security |
+| **framework** | **`lxml`** integration, delivery SDK handoff, parsing impact |
+
+## 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,48 @@
 ---
 name: code-review
-description: PR review for contentstack_utils — public API, __all__, lxml/deps, pytest.
+description: PR checklist—public API, __all__, semver, lxml/deps, pytest, secrets; aligns with JS utils where applicable.
 ---
 
-# Code review — `contentstack_utils`
+# Code review – Contentstack Utils Python
 
-## Checklist
+## When to use
 
-- [ ] **API:** New or changed **`Utils`** / **`Options`** / tag helpers reflected in **`contentstack_utils/__init__.py`** **`__all__`** and **README** if user-facing.
-- [ ] **Version:** **`setup.py` `version`** bumped when releasing behavioral or API changes (semver).
-- [ ] **Dependencies:** Any new **`install_requires`** entry documented; **`lxml`** usage stays appropriate for parsing/rendering.
-- [ ] **Tests:** **`pytest`** passes; add tests under **`tests/`** for new behavior.
-- [ ] **Secrets:** No tokens in repo; examples use placeholders only.
+- 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
+
+- [ ] **`contentstack_utils/__init__.py`** **`__all__`** and exports match **README** examples and intended surface (**`Utils`**, **`Options`**, **`GQL`**, **`Automate`**, embed types, **`addEditableTags`** / **`addTags`** / **`getTag`**).
+- [ ] **JS parity** — where methods mirror the JS utils SDK, **parameter names** and behavior stay consistent unless a documented breaking change.
+
+### Compatibility
+
+- [ ] No breaking **`Utils`** / **`Options`** / tag helpers without a **semver** plan; **`setup.py` `version`** bumped for user-visible changes.
+
+### Dependencies
+
+- [ ] **`lxml`** usage stays bounded to parsing/rendering paths; new **`install_requires`** documented in **README** / changelog.
+
+### Tests
+
+- [ ] **`pytest`** passes; tests added or extended under **`tests/`** for new behavior and edge cases.
+
+### Security
+
+- [ ] No hardcoded tokens; no logging of secrets in new code.
+
+### Severity (optional)
+
+| Level | Examples |
+|-------|----------|
+| **Blocker** | Breaking public API without approval; security issue; no tests where practical |
+| **Major** | Inconsistent behavior vs documented API; README examples wrong |
+| **Minor** | Style; minor docs |
 
 ## References
 
-- `.cursor/rules/code-review.mdc`
-- `.cursor/rules/dev-workflow.md`
+- **`skills/testing/SKILL.md`**
+- **`skills/contentstack-utils/SKILL.md`**

AGENTS.md

@@ -0,0 +1,47 @@
+---
+name: contentstack-utils
+description: Public API—Utils, Options, RTE/embedded, GQL, editable tags; JS parity; no bundled HTTP client.
+---
+
+# Contentstack Utils – SDK skill
+
+## When to use
+
+- Implementing or changing RTE/HTML rendering, embedded resolution, **GQL**, or editable-tag behavior.
+- Updating **`README.md`** / **`changelog.rst`** / **`setup.py`** for user-visible behavior.
+- Assessing semver impact of **`__init__.py`** exports and public classes.
+
+## Core entry points
+
+- **`Utils`** — **`contentstack_utils.utils`**: **`render_content`**, **`render`**, embedded/RTE resolution; subclasses **`Automate`**.
+- **`Options`** — **`contentstack_utils.render.options`**: rendering configuration passed into **`Utils`** methods.
+- **Editable tags** — **`entry_editable`**: **`addEditableTags`**, **`addTags`**, **`getTag`**; also exposed as **`Utils.addEditableTags`** / **`Utils.addTags`** / **`Utils.getTag`** for parity.
+
+## Features
+
+- **Embedded / RTE** — JSON and HTML paths through **`Utils`** and **`Automate`**; **metadata** via **`Metadata`**.
+- **Styles** — **`convert_style`** and **embedded** **StyleType** / **ItemType** where applicable.
+- **GQL** — **`GQL`** in **`gql.py`** for GraphQL-oriented HTML/helpers.
+
+## Public API and docs
+
+- **`contentstack_utils/__init__.py`** **`__all__`** and exports must match **README** examples and intended surface (**`Utils`**, **`Options`**, **`GQL`**, **`Automate`**, embed types, tag helpers).
+- **JS parity** — where methods mirror the JS utils SDK, keep **parameter names** and behavior consistent unless a documented breaking change.
+
+## Compatibility
+
+- Avoid breaking **`Utils`** / **`Options`** / tag helpers without a **semver** plan; bump **`setup.py` `version`** for user-visible changes.
+
+## Dependencies
+
+- **`lxml`** usage stays bounded to parsing/rendering paths; note any new **`install_requires`** in **README** / changelog if added to **`setup.py`**.
+
+## No network layer
+
+- This package does **not** ship HTTP clients or tokens.
+- Consumers often use **`contentstack.Stack`** (**Contentstack** package) to fetch entries, then **`Utils.render`** / **`Utils.render_content`** — keep **README** examples accurate.
+
+## References
+
+- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
+- **`skills/python-style/SKILL.md`**, **`skills/framework/SKILL.md`**

skills/README.md

@@ -1,10 +1,14 @@
 ---
-description: "Branches, venv, pytest, and lint for contentstack-utils-python"
-globs: ["**/*.py", "requirements.txt", "setup.py"]
-alwaysApply: false
+name: dev-workflow
+description: Branches, CI, venv, pytest, lint—standard workflow for Contentstack Utils Python.
 ---
 
-# Development workflow — `contentstack_utils`
+# Development workflow – Contentstack Utils Python
+
+## When to use
+
+- Setting up locally, opening a PR, or aligning with CI.
+- Answering “how do we run tests?” or “which branch targets `master`?”
 
 ## Before a PR
 
@@ -15,8 +19,9 @@ alwaysApply: false
 
 ## Branching
 
-- Follow org conventions: **`development`** / **`staging`** / **`master`**; PRs to **`master`** may be restricted (see **`.github/workflows/check-branch.yml`**).
+- Follow org conventions: **`development`** / **`staging`** / **`master`**; PRs to **`master`** may be restricted (see **`.github/workflows/check-branch.yml`**). Confirm with your team before opening PRs to **`master`**.
 
 ## Links
 
-- [`AGENTS.md`](../../AGENTS.md) · [`skills/contentstack-utils-python/SKILL.md`](../../skills/contentstack-utils-python/SKILL.md)
+- **`AGENTS.md`** — commands and layout overview.
+- **`skills/code-review/SKILL.md`** — pre-merge checklist.