Enh: Added cursor rules and skills

.cursor/rules/README.md

@@ -0,0 +1,37 @@
+# Cursor Rules — `contentstack_utils`
+
+Rules for **contentstack-utils-python**: Python **utils** package for **RTE / embedded** rendering, **GQL**, and **editable tags** (companion to the Contentstack Python SDK).
+
+## 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)

.cursor/rules/code-review.mdc

@@ -0,0 +1,27 @@
+---
+description: "PR checklist for contentstack_utils — public API, semver, tests, secrets"
+alwaysApply: true
+---
+
+# Code review — `contentstack_utils`
+
+## 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, 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`**.
+
+## Tests
+
+- **`pytest`** passes for changed behavior; add or extend tests under **`tests/`** for new branches and edge cases.
+
+## Security
+
+- No hardcoded tokens; no logging of secrets in new code.

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

@@ -0,0 +1,27 @@
+---
+description: "Contentstack Python Utils — Utils, Options, RTE/embedded, GQL, editable tags"
+globs: ["contentstack_utils/**/*.py"]
+alwaysApply: false
+---
+
+# Contentstack Python Utils (`contentstack_utils/`)
+
+## 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.
+
+## Companion SDK
+
+- Consumers often use **`contentstack.Stack`** ( **`Contentstack`** package) to fetch entries, then **`Utils.render`** / **`Utils.render_content`** on field data — keep examples in **README** accurate.
+
+## Docs
+
+- [Content Delivery API](https://un5gmtkzgk8eudfk1m0b5d8.julianrbryant.com/docs/developers/apis/content-delivery-api/)

.cursor/rules/dev-workflow.md

@@ -0,0 +1,22 @@
+---
+description: "Branches, venv, pytest, and lint for contentstack-utils-python"
+globs: ["**/*.py", "requirements.txt", "setup.py"]
+alwaysApply: false
+---
+
+# Development workflow — `contentstack_utils`
+
+## Before a PR
+
+1. **Install** — `pip install -r requirements.txt` and `pip install -e .` in a virtual environment.
+2. **`pytest`** — full suite under **`tests/`** must pass.
+3. **Lint / format** — run **ruff**, **black**, **flake8**, **isort** as configured for the repo (see **`requirements.txt`**).
+4. **Version** — update **`setup.py` `version`** for releases per semver.
+
+## Branching
+
+- Follow org conventions: **`development`** / **`staging`** / **`master`**; PRs to **`master`** may be restricted (see **`.github/workflows/check-branch.yml`**).
+
+## Links
+
+- [`AGENTS.md`](../../AGENTS.md) · [`skills/contentstack-utils-python/SKILL.md`](../../skills/contentstack-utils-python/SKILL.md)

.cursor/rules/python.mdc

@@ -0,0 +1,34 @@
+---
+description: "Python conventions for contentstack_utils package and setup"
+globs:
+  - "contentstack_utils/**/*.py"
+  - "setup.py"
+alwaysApply: false
+---
+
+# Python — `contentstack_utils`
+
+## Layout
+
+- **`contentstack_utils/utils.py`** — **`Utils`** class (rendering, embedded items); delegates **editable tag** static methods to **`entry_editable`**.
+- **`contentstack_utils/render/`** — **`Options`** and render-related code.
+- **`contentstack_utils/helper/`** — **Metadata**, **NodeToHtml**, **converter**.
+- **`contentstack_utils/embedded/`** — **ItemType**, **StyleType**.
+- **`contentstack_utils/gql.py`**, **`automate.py`**, **`entry_editable.py`** — feature modules.
+
+## Style
+
+- Match existing patterns: **typing** hints where already used; **pylint** pragmas only where established.
+- Prefer **small, focused** changes; avoid drive-by refactors unrelated to the task.
+
+## Imports
+
+- **`lxml.etree`** — HTML/XML parsing in **`utils`** and helpers; keep usage consistent with existing error handling.
+
+## Packaging
+
+- **`setup.py`** — **`name`**, **`version`**, **`packages=find_packages()`**; keep **`install_requires`** accurate if dependencies change.
+
+## Security
+
+- Do not log **delivery tokens**, **API keys**, or stack secrets.

.cursor/rules/testing.mdc

@@ -0,0 +1,26 @@
+---
+description: "pytest for contentstack-utils-python"
+globs:
+  - "tests/**/*.py"
+alwaysApply: false
+---
+
+# Testing — `contentstack_utils`
+
+## pytest
+
+- Tests live in **`tests/`** as **`test_*.py`** modules.
+- Run: **`pytest`** from the repo root (with venv and **`requirements.txt`** installed).
+- Optional HTML report: **`pytest --html=tests/test-report/test-report.html --self-contained-html`** (path may vary; align with local **pytest-html** output).
+
+## Coverage
+
+- **`coverage run -m pytest`** then **`coverage report -m`** (or **`coverage html`**) for coverage review.
+
+## Mocks
+
+- Shared mock data under **`tests/mocks/`** (e.g. **supercharged** fixtures) — reuse for new cases instead of duplicating large JSON.
+
+## Hygiene
+
+- No committed **`pytest.mark.skip`** or **`xfail`** without justification; no **`breakpoint()`** left in CI paths.

AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md — AI / automation context
+
+## Project
+
+| | |
+|---|---|
+| **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) |
+
+## Tech stack
+
+| Area | Details |
+|------|---------|
+| **Language** | **Python** (`python_requires` in `setup.py`; classifiers list 3.6–3.9; dev tooling in `requirements.txt` may need a newer interpreter) |
+| **Package** | **`setuptools`** — `find_packages()`, `contentstack_utils/` |
+| **Runtime deps** | **`lxml`** (XML/HTML parsing in `utils.py` and helpers) |
+| **Tests** | **pytest** + **pytest-cov**, **pytest-html** (optional HTML report) |
+| **Lint / format** | **ruff**, **black**, **flake8**, **isort** (see `requirements.txt`) |
+
+## Source layout
+
+| Path | Role |
+|------|------|
+| `contentstack_utils/utils.py` | **`Utils`** — `render_content`, embedded/RTE flows; extends **`Automate`** |
+| `contentstack_utils/render/options.py` | **`Options`** for rendering |
+| `contentstack_utils/helper/` | **Metadata**, **NodeToHtml**, **converter** (e.g. `convert_style`) |
+| `contentstack_utils/embedded/` | **ItemType**, **StyleType** |
+| `contentstack_utils/gql.py` | **GQL** helpers |
+| `contentstack_utils/automate.py` | **`Automate`** base for automation-style rendering |
+| `contentstack_utils/entry_editable.py` | **`addEditableTags`**, **`addTags`**, **`getTag`**; re-exported via **`Utils`** static methods and package **`__init__`** |
+| `contentstack_utils/__init__.py` | Public exports — keep **`__all__`** aligned with documented API |
+| `tests/` | pytest modules (`test_*.py`), mocks under `tests/mocks/` |
+
+## Common commands
+
+```bash
+python -m venv .venv && source .venv/bin/activate  # or equivalent on Windows
+pip install -r requirements.txt
+pip install -e .
+pytest
+pytest --html=tests/test-report/test-report.html --self-contained-html
+coverage run -m pytest && coverage report -m
+```
+
+## Security
+
+- Do not commit **API keys**, **delivery tokens**, or other secrets. Examples in **`README.md`** use placeholders only.
+
+## Further guidance
+
+- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
+- **Skills:** [`skills/README.md`](skills/README.md)
+
+Product docs: [Content Delivery API](https://un5gmtkzgk8eudfk1m0b5d8.julianrbryant.com/docs/developers/apis/content-delivery-api/).

skills/README.md

@@ -0,0 +1,10 @@
+# Project skills — `contentstack_utils`
+
+| 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 |
+
+**Overview:** [`AGENTS.md`](../AGENTS.md) · **Rules:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)

skills/code-review/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: code-review
+description: PR review for contentstack_utils — public API, __all__, lxml/deps, pytest.
+---
+
+# Code review — `contentstack_utils`
+
+## Checklist
+
+- [ ] **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.
+
+## References
+
+- `.cursor/rules/code-review.mdc`
+- `.cursor/rules/dev-workflow.md`

skills/contentstack-utils-python/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: contentstack-utils-python
+description: contentstack_utils — Python RTE/embedded rendering, Options, GQL, editable tags.
+---
+
+# Contentstack Python Utils skill
+
+## Entry
+
+- **`Utils`** — **`contentstack_utils.utils`**: **`render_content`**, **`render`**, embedded item automation via **`Automate`**.
+- **`Options`** — configure rendering behavior for **`Utils`** calls.
+
+## Structure
+
+- **`Automate`** — **`automate.py`**: shared automation/rendering flow used by **`Utils`**.
+- **Helpers** — **`helper/metadata.py`**, **`helper/node_to_html.py`**, **`helper/converter.py`**.
+- **Embedded** — **`embedded/item_type.py`**, **`embedded/styletype.py`**.
+- **GQL** — **`gql.py`**.
+- **Live preview / tags** — **`entry_editable.py`**; static wrappers on **`Utils`** keep JS-style parameter names where needed.
+
+## Extending
+
+- Prefer matching **JS contentstack-utils** behavior when the feature exists there; document intentional divergences.
+- Keep **`lxml`** usage in parsing/rendering layers; avoid broad new runtime deps without packaging updates.
+
+## Companion package
+
+- **`Contentstack`** (delivery SDK) fetches entries; this package renders RTE/embedded fields — see **README** examples.
+
+## Docs
+
+- [Content Delivery API](https://un5gmtkzgk8eudfk1m0b5d8.julianrbryant.com/docs/developers/apis/content-delivery-api/)
+
+## Rule shortcut
+
+- `.cursor/rules/contentstack-utils-python.mdc`

skills/framework/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: framework
+description: lxml and companion Contentstack Python SDK — how utils fits in the stack.
+---
+
+# Framework skill — `lxml` + Contentstack Python ecosystem
+
+## Integration points
+
+- **`lxml.etree`** — parsing and tree operations in **`utils.py`** and related helpers; errors should remain predictable for malformed HTML/XML inputs.
+- **Contentstack delivery SDK** — consumers fetch **`entry`** data with **`contentstack.Stack`**, then pass fields into **`Utils.render`** / **`Utils.render_content`** with **`Options`**.
+
+## When to change
+
+- **Parsing behavior** — verify impact on **RTE** output and existing **`tests/`** fixtures.
+- **New dependencies** — add to **`setup.py` `install_requires`** and document; prefer stdlib or existing stack (**`lxml`** already required).
+
+## Testing
+
+- **Unit** — **`tests/test_*.py`** with mocks under **`tests/mocks/`** where applicable.
+
+## Rule shortcut
+
+- `.cursor/rules/contentstack-utils-python.mdc`
+- `.cursor/rules/python.mdc`

skills/testing/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: testing
+description: pytest and coverage for contentstack-utils-python.
+---
+
+# Testing — `contentstack_utils`
+
+## Commands
+
+| Goal | Command |
+|------|---------|
+| Full suite | `pytest` |
+| HTML report | `pytest --html=tests/test-report/test-report.html --self-contained-html` |
+| Coverage (example) | `coverage run -m pytest && coverage report -m` |
+
+## Layout
+
+- **`tests/test_*.py`** — feature-focused modules (**utils**, **GQL**, **metadata**, **editable tags**, etc.).
+- **`tests/mocks/`** — shared fixture-style data; extend for new scenarios.
+
+## Setup
+
+- Install **`requirements.txt`** in a venv; **`pip install -e .`** for editable package tests.
+
+## References
+
+- `.cursor/rules/testing.mdc`