Update documentation to deprecate CocoaPods for new projects in favor of Swift Package Manager

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### Documentation
+
+- 2026-04-02: Added CocoaPods deprecation guidance for **new** projects—**SPM** is recommended for ContentstackUtils; clarified companion role vs the core Swift CDA SDK. Updated README (Important section), added root **DEPRECATION.md** (customer-facing only), added **Docs/overview.md** banner with link to `DEPRECATION.md`.
+
 ## [1.4.0] - 2026-03-30
 
 ### Enhancement

DEPRECATION.md

@@ -0,0 +1,33 @@
+# CocoaPods distribution for ContentstackUtils
+
+This notice applies to developers who integrate **ContentstackUtils** using **CocoaPods** (`ContentstackUtils` pod).
+
+## What this package is
+
+**ContentstackUtils** is a **companion library** for the [Contentstack Swift SDK](https://github.com/contentstack/contentstack-swift). It provides utilities (for example JSON RTE rendering and embedded items) for use **alongside** the Swift Content Delivery API (CDA) client. It is **not** a replacement for the core CDA SDK—you still use the [Swift SDK](https://github.com/contentstack/contentstack-swift) for stack, queries, and delivery.
+
+## What we recommend for new work
+
+For **new** projects and new integrations, we recommend adding **ContentstackUtils** with **Swift Package Manager (SPM)** from this repository, and using the **Swift SDK** via SPM as well. That keeps your dependency graph aligned with current tooling and our primary distribution path.
+
+- **Contentstack Swift SDK (source):** [github.com/contentstack/contentstack-swift](https://github.com/contentstack/contentstack-swift)  
+- **Swift SDK on Swift Package Index:** [swiftpackageindex.com/contentstack/contentstack-swift](https://swiftpackageindex.com/contentstack/contentstack-swift)  
+- **Swift CDA reference:** [Content Delivery SDK — Swift reference](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift/reference)
+
+**Version alignment:** Use ContentstackUtils versions that match the guidance in this repository’s README (keep Utils in step with the Swift SDK version you use).
+
+We are **deprecating CocoaPods as the recommended way** to add ContentstackUtils for **new** work. CocoaPods remains part of the broader ecosystem, but our product direction favors **SPM** for Apple platforms. For background on how the CocoaPods ecosystem is evolving, see [CocoaPods Specs Repo](https://blog.cocoapods.org/CocoaPods-Specs-Repo/).
+
+## If you already use CocoaPods
+
+**Existing** apps that already depend on the `ContentstackUtils` pod can continue to ship as they do today. You are not required to migrate on a fixed deadline to keep using what you have. When you are ready to standardize on SPM or refresh dependencies, plan a migration at your own pace.
+
+## Maintenance and features
+
+We continue to maintain ContentstackUtils for supported integration paths. **New** feature work and documentation will emphasize **SPM** and the Swift SDK. CocoaPods-based setups may receive necessary maintenance but are not our focus for new capabilities.
+
+## Support
+
+Questions or help with your integration: [support@contentstack.io](mailto:support@contentstack.io).
+
+See also the **Important** section at the top of the [README](./README.md).

Docs/overview.md

@@ -0,0 +1,7 @@
+# ContentstackUtils — overview
+
+## Important
+
+**ContentstackUtils** is a **companion** to the [Contentstack Swift SDK](https://github.com/contentstack/contentstack-swift), not the core CDA client. Prefer **Swift Package Manager** for new work; the **CocoaPods** pod is **not** recommended for new projects. Existing CocoaPods users can keep shipping until they choose to migrate.
+
+Full details: **[DEPRECATION.md](../DEPRECATION.md)** · [README](../README.md) · [Swift SDK reference](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift/reference)

README.md

@@ -1,8 +1,19 @@
 # ![Contentstack](https://www.contentstack.com/docs/static/images/contentstack.png)
 
-# Contentstack Swift SDK
+# ContentstackUtils
+
 ![ContentstackUtils CI](https://github.com/contentstack/contentstack-utils-swift/workflows/ContentstackUtils%20CI/badge.svg)
 
+## Important
+
+**ContentstackUtils** is a **companion** library for the [Contentstack Swift SDK](https://github.com/contentstack/contentstack-swift)—utilities for JSON RTE, embedded items, and related helpers; it is **not** the core Content Delivery API (CDA) client. Add **ContentstackUtils** with Swift Package Manager from [`contentstack/contentstack-utils-swift`](https://github.com/contentstack/contentstack-utils-swift), add the [Swift SDK](https://github.com/contentstack/contentstack-swift) the same way (see also [Swift Package Index](https://swiftpackageindex.com/contentstack/contentstack-swift)), and **align versions** between them as described in this README.
+
+We are **deprecating CocoaPods** (`pod 'ContentstackUtils'`) as the recommended integration path for **new** projects—prefer SPM. **Existing** CocoaPods users can keep shipping; migrate when it suits you. This applies only to the **CocoaPods delivery channel**, not to the Swift libraries themselves.
+
+Read the full customer-facing notice: **[DEPRECATION.md](./DEPRECATION.md)**. Swift CDA reference: [Swift SDK reference](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift/reference). Optional context: [CocoaPods Specs Repo](https://blog.cocoapods.org/CocoaPods-Specs-Repo/).
+
+---
+
 Contentstack is a headless CMS with an API-first approach. It is a CMS that developers can use to build powerful cross-platform applications in their favorite languages. Build your application frontend, and Contentstack will take care of the rest. [Read More](https://www.contentstack.com/).
 
 Contentstack provides iOS SDK to build application on top of iOS. Given below is the detailed guide and helpful resources to get started with our iOS SDK.