DX | 20-04-2026 | Release dev -> stg

.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

@@ -0,0 +1,48 @@
+# Contentstack Utils (Dart) – Agent guide
+
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
+
+## What this repo is
+
+| Field | Detail |
+|-------|--------|
+| **Name:** | [contentstack-utils-dart](https://github.com/contentstack/contentstack-utils-dart) — pub package **`contentstack_utils`** |
+| **Purpose:** | Dart utilities to render rich text and embedded entries from Contentstack **Delivery JSON** (classic RTE, Supercharged RTE, and GraphQL-shaped SRTE). Typically used with **`package:contentstack`**. |
+| **Out of scope (if any):** | **No HTTP client** — no stack calls, API keys, delivery tokens, or retries. Network and auth belong in the [Contentstack Dart SDK](https://pub.dev/packages/contentstack). |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+|------|---------|
+| **Language** | Dart — `environment.sdk` in `pubspec.yaml` (`>=2.12.0 <4.0.0`) |
+| **Build** | Pub — `pubspec.yaml`, `pubspec.lock` |
+| **Tests** | `package:test` — `dart test`; files `test/*_test.dart` |
+| **Lint / coverage** | `analysis_options.yaml`; coverage under `coverage/` / `lcov.info` when generated |
+| **Other** | Runtime deps: `path`, `html`, `logger`, `lint` (see `pubspec.yaml`) |
+
+## Commands (quick reference)
+
+| Command type | Command |
+|--------------|---------|
+| **Build** | `dart pub get` |
+| **Test** | `dart test` |
+| **Lint** | `dart analyze .` and `dart format .` |
+
+**CI:** branch policy — `.github/workflows/check-branch.yml`; SCA — `.github/workflows/sca-scan.yml`; publish on tags — `.github/workflows/publish.yml`.
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | `skills/dev-workflow/SKILL.md` | Branches, CI, commands, PR expectations, optional TDD |
+| **Contentstack Utils API** | `skills/contentstack-utils/SKILL.md` | `Utils`, `GQL`, `Option`, RTE/embedded JSON, errors, boundaries with `package:contentstack` |
+| **Dart** | `skills/dart/SKILL.md` | Dart SDK, `lib/` layout, imports, analyzer, naming |
+| **Testing** | `skills/testing/SKILL.md` | `package:test`, `test/mock/`, coverage, offline-only tests |
+| **Code review** | `skills/code-review/SKILL.md` | PR checklist, Blocker / Major / Minor |
+| **Framework / tooling** | `skills/framework/SKILL.md` | `pubspec`, lockfile, `analysis_options.yaml`, CI security, shared deps (`html`, `logger`) |
+
+An index with “when to use” hints is in `skills/README.md`.
+
+## Using Cursor (optional)
+
+If you use **Cursor**, `.cursor/rules/README.md` only points to **`AGENTS.md`** — same docs as everyone else.

CHANGELOG.md

@@ -1,4 +1,10 @@
-# Changelog
+# CHANGELOG
+
+### **APR-09-2026**
+
+#### Documentation
+
+- Add deprecation notice and migration guidance to the Content Delivery API. See [DEPRECATION.md](DEPRECATION.md).
 
 ## v1.1.1
 

DEPRECATION.md

@@ -0,0 +1,27 @@
+# Deprecation notice: Contentstack Dart Utils (pub.dev)
+
+This page is for **developers using the Contentstack Dart Utils** package published on **pub.dev** as [`contentstack_utils`](https://pub.dev/packages/contentstack_utils).
+
+## What this means for you
+
+**We are deprecating this package as the recommended path for new Dart and Flutter work.** If you are **starting a new project**, use our **[Content Delivery API (CDA)](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)** and implement rich text / JSON RTE handling in your app using current product documentation.
+
+**If you already ship an app** that depends on `contentstack_utils`, you can **keep using it**. Your integration continues to work. Plan migration when it fits your release schedule—you do not have to change immediately.
+
+The **[Contentstack Dart SDK](https://github.com/contentstack/contentstack-dart)** is deprecated on the same timeline; see that repository’s **DEPRECATION.md**.
+
+## What to use for new projects
+
+| | Link |
+|---|------|
+| **Content Delivery API** | [Content Delivery API documentation](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) |
+
+## Why we are making this change
+
+We are focusing investment on **direct API usage** and **documented integration patterns** for Dart and Flutter. This repository will remain in **maintenance**: we may address critical or security issues where we can, but **we do not plan new features** in this package.
+
+## Support for this package going forward
+
+This repository will stay in **maintenance** as described above. Feature work and new capabilities should be built against the **Content Delivery API** and your application code.
+
+If you need help choosing a migration path or timing, contact **[Contentstack support](https://www.contentstack.com/)** or your account team.

README.md

@@ -1,4 +1,10 @@
-# A Contentstack-Utils library for Dart developers
+# ![Contentstack](https://www.contentstack.com/docs/static/images/contentstack.png)
+
+## Important: Dart Utils and pub.dev
+
+**We are deprecating** the **Contentstack Utils** Dart package on pub.dev as the supported path for **new** development. **New Dart or Flutter projects should use the [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)** and your own handling for rich text / JSON RTE, following current documentation.
+
+**Already using this package?** You can keep shipping with your current dependencies and migrate when it makes sense for your app. More detail: **[DEPRECATION.md](DEPRECATION.md)**.
 
 ![Coverage](https://github.com/contentstack/contentstack-utils-dart/blob/master/coverage_badge.svg?sanitize=true)
 

skills/README.md

@@ -0,0 +1,16 @@
+# Skills – Contentstack Utils (Dart)
+
+Source of truth for detailed guidance. Read **`AGENTS.md`** first, then open the skill that matches your task.
+
+## When to use which skill
+
+| Skill folder | Use when |
+|--------------|----------|
+| `dev-workflow` | Branches, CI expectations, build/test/lint commands, PR process, optional TDD |
+| `contentstack-utils` | Public API (`Utils`, `GQL`, `Option`), RTE/embedded JSON, `FormatException` / `ErrorMessages` |
+| `dart` | Dart version constraints, `lib/` layout, imports, analyzer/format, package naming |
+| `testing` | Writing tests, `test/mock/` fixtures, coverage, no live credentials |
+| `code-review` | Reviewing or preparing a PR — API stability, security, tests |
+| `framework` | `pubspec` / lockfile, `analysis_options.yaml`, CI scans (OSV), shared runtime libraries |
+
+Each folder contains **`SKILL.md`** with YAML frontmatter (`name`, `description`).

skills/code-review/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: code-review
+description: Use when reviewing PRs or before opening a PR — API design, backward compatibility, dependencies, security, tests
+---
+
+# Code review – Contentstack Utils (Dart)
+
+## When to use
+
+- Reviewing a teammate’s PR or self-review before submit.
+- Verifying API stability, errors, semver, SCA, and test coverage.
+
+## Instructions
+
+### API design and stability
+
+- [ ] **Public API:** Changes to **`Utils`**, **`GQL`**, **`Option`**, or barrel exports are documented in **`README.md`** / **`CHANGELOG.md`** when user-facing.
+- [ ] **Backward compatibility:** Breaking changes require explicit semver / changelog; **`GQL`** remains importable from **`package:contentstack_utils/src/GQL.dart`** for downstream SDKs.
+- [ ] **Naming:** Matches existing methods (**`jsonToHTML`**, **`render`**, **`renderContent`**).
+
+### Error handling
+
+- [ ] Invalid JSON / embedded input throws **`FormatException`** with **`ErrorMessages`** (or documented behavior); no silent failures.
+- [ ] Strings use **`ErrorMessages`** in **`lib/src/constants/ErrorMessages.dart`** where the library already centralizes them.
+
+### Dependencies and security
+
+- [ ] New or upgraded deps are justified; **`pubspec.lock`** updated intentionally.
+- [ ] Consider **`.github/workflows/sca-scan.yml`** (OSV, **`dart pub outdated`**) on dependency PRs.
+
+### Testing
+
+- [ ] **`dart test`** passes; new behavior covered under **`test/`** with **`test/mock/`** where appropriate.
+- [ ] No flaky or network-dependent tests.
+
+### Severity (optional)
+
+- **Blocker:** Breaking public API without approval, security regression, no tests for new code.
+- **Major:** Inconsistent errors, missing changelog for user-visible change.
+- **Minor:** Style, small doc nits.
+
+## References
+
+- **`skills/testing/SKILL.md`** — test expectations
+- **`skills/contentstack-utils/SKILL.md`** — public API surface
+- **`AGENTS.md`** — lint/test commands

skills/contentstack-utils/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: contentstack-utils
+description: Use when implementing or changing Utils, GQL, Option, RTE/embedded JSON, and ErrorMessages — alignment with package:contentstack
+---
+
+# Contentstack Utils API – Contentstack Utils (Dart)
+
+## When to use
+
+- Adding or changing **`Utils`**, **`GQL`**, **`Option`**, **`Metadata`**, **`StyleType`**, or **`Automate`** behavior.
+- Defining how **`FormatException`** and **`ErrorMessages`** apply to invalid JSON or embedded input.
+- Ensuring imports remain stable for **`package:contentstack`** consumers.
+
+## Instructions
+
+### Entry points
+
+- **Barrel:** `package:contentstack_utils/contentstack_utils.dart` — **`Utils`**, exported **`Metadata`**, **`StyleType`**.
+- **Option:** `package:contentstack_utils/src/model/Option.dart` — **`renderOption(Map, Metadata)`**, **`Option.entry(Map)`**.
+- **GQL:** `package:contentstack_utils/src/GQL.dart` — **`GQL.jsonToHTML`**. Not re-exported from the barrel; import explicitly.
+
+### Boundaries
+
+- This package only transforms **fetched** entry JSON (`_embedded_items`, RTE HTML). **No HTTP** — stack credentials and delivery API calls belong in the [Contentstack Dart SDK](https://pub.dev/packages/contentstack).
+
+### Public behavior
+
+- **`Utils.render`**, **`Utils.renderContent`**, **`Utils.jsonToHTML`** — walk embedded items, resolve RTE paths, render via **`Option`**; invalid input throws **`FormatException`** with **`ErrorMessages`** text.
+- **`GQL.jsonToHTML`** — GraphQL-shaped SRTE (`embedded_itemsConnection`, nested `json`).
+- Centralize user-facing strings in **`lib/src/constants/ErrorMessages.dart`**.
+- RTE parsing uses **`package:html`**; helpers may use **`package:logger`** — stay consistent with **`lib/src/helper/Automate.dart`**.
+
+### Versioning and docs
+
+- User-visible changes: update **`README.md`** and **`CHANGELOG.md`**; follow **`jsonToHTML`** naming in code (avoid README typos like `jsonToHtml`).
+
+## References
+
+- **`skills/dart/SKILL.md`** — layout and imports
+- **`skills/testing/SKILL.md`** — tests for API changes
+- [Contentstack documentation](https://www.contentstack.com/docs)
+- [contentstack_utils on pub.dev](https://pub.dev/packages/contentstack_utils)

skills/dart/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: dart
+description: Use when editing Dart sources — SDK constraints, lib layout, imports, analyzer, formatting, dependencies
+---
+
+# Dart – Contentstack Utils (Dart)
+
+## When to use
+
+- Editing any **`*.dart`** file under **`lib/`** or **`test/`**.
+- Changing **`pubspec.yaml`** dependency lists (coordinate with **`skills/framework/SKILL.md`** for lockfile and CI impact).
+- Fixing or discussing **`analysis_options.yaml`** behavior.
+
+## Instructions
+
+### Language and SDK
+
+- Honor **`environment.sdk`** in **`pubspec.yaml`** (`>=2.12.0 <4.0.0`). Do not require a newer SDK in code without updating the constraint deliberately.
+
+### Analyzer and formatting
+
+- Lints are driven by **`analysis_options.yaml`** (includes `package:pedantic/analysis_options.yaml` today — ensure the resolved package exists or fix the include with the team).
+- Run **`dart format .`** before PRs.
+
+### Package layout and naming
+
+- **Barrel:** **`lib/contentstack_utils.dart`**
+- **Implementation:** **`lib/src/`** — `helper/`, `model/`, `embedded/`, `constants/`
+- **Files:** `PascalCase.dart` under **`lib/src/`**; **`test/*_test.dart`** use snake_case.
+
+### Imports
+
+- Prefer **`package:contentstack_utils/...`** in library code.
+- Tests may import the barrel plus **`package:contentstack_utils/src/...`** (e.g. **`Automate.dart`**) to exercise internals — follow existing tests.
+
+### Dependencies
+
+- **Runtime:** `path`, `html`, `logger`, `lint` — keep the package lean; no new packages without review.
+- **Typing:** JSON is often **`Map`** / dynamic; improve safety incrementally and match patterns in **`lib/src/helper/Automate.dart`** and **`lib/src/model/Option.dart`**.
+
+## References
+
+- **`skills/contentstack-utils/SKILL.md`** — public API behavior
+- **`skills/framework/SKILL.md`** — lockfile, CI, analyzer policy changes
+- **`AGENTS.md`** — command quick reference

skills/dev-workflow/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: dev-workflow
+description: Use when branching, running CI-related commands, opening PRs, or deciding on TDD for this package
+---
+
+# Development workflow – Contentstack Utils (Dart)
+
+## When to use
+
+- Choosing a base branch or understanding merge policy into **`master`**.
+- Running build, test, analyze, or format before a PR.
+- Publishing (maintainers) or interpreting GitHub Actions workflows.
+- Deciding whether to write tests first (TDD).
+
+## Instructions
+
+### Branches
+
+- Use feature branches (e.g. `feat/...`, `fix/...`).
+- **`.github/workflows/check-branch.yml`** blocks PRs into **`master`** unless the head branch is **`staging`**. Prefer PRs against **`staging`** per team policy.
+
+### Commands
+
+- **Dependencies:** `dart pub get`
+- **Tests:** `dart test`
+- **Analyze:** `dart analyze .`
+- **Format:** `dart format .`
+
+Run **`dart analyze .`** and **`dart test`** before requesting review. There are **no** live-stack integration tests — only JSON fixtures under **`test/mock/`**.
+
+### Pull requests
+
+- Keep public API changes backward compatible or bump semver and update **`CHANGELOG.md`**.
+- Dependency changes: consider **`.github/workflows/sca-scan.yml`** (OSV on **`pubspec.lock`**, **`dart pub outdated`**).
+
+### Security and compliance (CI)
+
+- **`.github/workflows/sca-scan.yml`** — dependency / OSV signals.
+- **`.github/workflows/policy-scan.yml`** — **`SECURITY.md`** and **`LICENSE`** (public repos).
+
+### Publishing (maintainers)
+
+- **`.github/workflows/publish.yml`** — publish on tags matching `v*.*.*` via **`dart pub publish`** (after dry-run in workflow).
+
+### Optional TDD
+
+If the team uses TDD: RED–GREEN–REFACTOR; fixture shapes in **`test/mock/`** should mirror Delivery / GQL payloads. Details: **`skills/testing/SKILL.md`**.
+
+## References
+
+- **`skills/testing/SKILL.md`** — test layout and fixtures
+- **`skills/code-review/SKILL.md`** — PR checklist
+- **`AGENTS.md`** — commands quick reference

skills/framework/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: framework
+description: Use when touching pubspec/lockfile, analysis_options, CI security workflows, or shared runtime deps (html, logger, path)
+---
+
+# Framework and tooling – Contentstack Utils (Dart)
+
+## When to use
+
+- Bumping or adding dependencies in **`pubspec.yaml`** / **`pubspec.lock`**.
+- Changing **`analysis_options.yaml`** or lint includes.
+- Editing **`.github/workflows/sca-scan.yml`**, **`.github/workflows/publish.yml`**, or policy-related CI.
+- Refactoring shared library usage (**`package:html`**, **`package:logger`**, **`package:path`**) across **`lib/`**.
+
+This package has **no** HTTP client, retries, or native modules — only Pub, analyzer, CI, and the runtime libraries listed in **`pubspec.yaml`**.
+
+## Instructions
+
+### Pub
+
+- **Install:** **`dart pub get`**.
+- **Lockfile:** Commit **`pubspec.lock`** for reproducible builds and OSV scanning.
+- Before merging dep changes: **`dart test`** and **`dart analyze .`**.
+
+### Analysis and lint
+
+- **`analysis_options.yaml`** must resolve included packages; align **`lint`** / **`lints`** with the team before large policy changes.
+- **Runtime deps:** `path`, `html`, `logger`, `lint` — keep minimal.
+- **Dev:** `test`, `lints`.
+
+### CI security
+
+- **`.github/workflows/sca-scan.yml`:** **`dart pub outdated`**, OSV on **`pubspec.lock`**.
+- **`.github/workflows/policy-scan.yml`:** **`SECURITY.md`**, **`LICENSE`** (public repos).
+
+### Publishing
+
+- **`.github/workflows/publish.yml`:** tag pattern **`v*.*.*`**, **`dart pub publish`** after dry-run.
+
+## References
+
+- **`skills/dart/SKILL.md`** — everyday Dart conventions
+- **`skills/code-review/SKILL.md`** — dependency / security review
+- **`skills/contentstack-utils/SKILL.md`** — API behavior (orthogonal to version bumps)
+- **`AGENTS.md`** — workflow file pointers