Add AGENTS.md and related SKILL documentation

.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 iOS Persistence – Agent guide
+
+*Universal entry point* for contributors and AI agents. Detailed conventions live in **skills/*/SKILL.md**.
+
+## What this repo is
+
+| Field | Detail |
+| --- | --- |
+| *Name:* | https://github.com/contentstack/contentstack-ios-persistence |
+| *Purpose:* | iOS library that persists Contentstack sync data locally so apps can work offline. Ships a shared core plus Core Data and Realm adapters consumed via CocoaPods. |
+| *Out of scope (if any):* | Not a standalone HTTP client; network and sync protocol come from the **Contentstack** iOS SDK dependency. Does not ship the example app (see [contentstack-ios-persistence-example](https://github.com/contentstack/contentstack-ios-persistence-example)). |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| Language | Objective-C (primary); Swift-compatible module imports documented in README. iOS deployment target **12.0** (see podspecs). |
+| Build | **Xcode** workspace `ContentstackPersistence.xcworkspace`; **CocoaPods** (`Podfile`, `pod install`). Key sources: `ContentstackPersistence/`, `ContentstackPersistenceCoredata/`, `ContentstackPersistenceRealm/`. Podspecs: `ContentstackPersistence.podspec`, `ContentstackPersistenceCoreData.podspec`, `ContentstackPersistenceRealm.podspec`. |
+| Tests | **XCTest** target `ContentstackPersistenceTests`; tests under `ContentstackPersistenceTests/`. |
+| Lint / coverage | No SwiftLint / shared coverage config in-repo; follow team standards if added later. |
+| Other | Dependencies: **Contentstack** iOS SDK, **Realm** (Realm subspec). Optional persistence: Core Data vs Realm via separate pods. |
+
+## Commands (quick reference)
+
+| Command Type | Command |
+| --- | --- |
+| Build | `pod install` then `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -sdk iphonesimulator build` |
+| Test | `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -destination 'platform=iOS Simulator,name=iPhone 16' test` (adjust simulator name to one installed locally) |
+| Lint | *(none configured)* |
+
+**CI:** PR checks include branch policy (`.github/workflows/check-branch.yml`), Snyk SCA (`.github/workflows/sca-scan.yml`), and policy scans (`.github/workflows/policy-scan.yml`). Jira linkage: `.github/workflows/issues-jira.yml`.
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Dev workflow & CI | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, build/test, PR expectations, CI overview |
+| SDK & public API | [skills/contentstack-ios-persistence-sdk/SKILL.md](skills/contentstack-ios-persistence-sdk/SKILL.md) | Entry points, pods, sync/persistence boundaries, versioning |
+| Objective-C / Swift & layout | [skills/objc-swift-ios/SKILL.md](skills/objc-swift-ios/SKILL.md) | Language conventions and repository layout |
+| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | XCTest layout, naming, fixtures, secrets |
+| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist for this repo |
+| iOS platform & packaging | [skills/ios-persistence-platform/SKILL.md](skills/ios-persistence-platform/SKILL.md) | CocoaPods, Core Data, Realm, Xcode workspace |
+
+An index with “when to use” hints is in [skills/README.md](skills/README.md).
+
+## Using Cursor (optional)
+
+If you use *Cursor*, [.cursor/rules/README.md](.cursor/rules/README.md) only points to *AGENTS.md*—same docs as everyone else.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2012-2023 Contentstack (http://app.contentstack.com)
+Copyright (c) 2012-2026 Contentstack (http://app.contentstack.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

skills/README.md

@@ -0,0 +1,16 @@
+# Skills – Contentstack iOS Persistence
+
+Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task.
+
+## When to use which skill
+
+| Skill folder | Use when |
+| --- | --- |
+| dev-workflow | Branching, PRs to `master`/`next`, CI expectations, local build and test commands |
+| contentstack-ios-persistence-sdk | Changing public API, `SyncManager`, stores, podspecs, or integration with Contentstack SDK |
+| objc-swift-ios | Objective-C/Swift style, file layout, headers, and module boundaries in this repo |
+| testing | Adding or changing XCTest code, test data, or simulator-only concerns |
+| code-review | Reviewing or preparing a PR against this repository’s expectations |
+| ios-persistence-platform | CocoaPods, Realm vs Core Data, Xcode workspace/schemes, iOS deployment targets |
+
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

skills/code-review/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: code-review
+description: PR checklist and severity guidance for contentstack-ios-persistence changes
+---
+
+# Code review – Contentstack iOS Persistence
+
+## When to use
+
+- You are reviewing a PR or preparing one for this repository
+- You need a consistent checklist aligned with CI and product boundaries
+
+## Instructions
+
+### Before you approve
+
+- **Branch policy:** Confirm the PR meets `.github/workflows/check-branch.yml` expectations (merges to `master` from `next` where required).
+- **Build:** Workspace builds after `pod install`; all three podspec-relevant targets remain consistent if core APIs changed.
+- **Tests:** New behavior has XCTest coverage where practical; no committed secrets.
+- **Pods:** `Podfile` / `Podfile.lock` changes are intentional; dependency ranges in podspecs match release intent.
+- **Docs:** User-visible API or setup changes update [README.md](../../README.md) or product docs links as needed.
+- **Security / compliance:** No credentials in code; Talisman-sensitive files respected.
+
+### Optional severity (for discussion)
+
+| Level | Examples |
+| --- | --- |
+| **Blocker** | Breaks consumers’ public API without semver major plan; security issue; build broken |
+| **Major** | Missing tests for risky logic; incorrect podspec dependency; sync/data loss risk |
+| **Minor** | Style nits, non-user-facing refactors, doc typos |
+
+### CODEOWNERS
+
+- Follow [CODEOWNERS](../../CODEOWNERS) for required reviewers.
+
+## References
+
+- [dev-workflow](../dev-workflow/SKILL.md)
+- [testing](../testing/SKILL.md)
+- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md)

skills/contentstack-ios-persistence-sdk/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: contentstack-ios-persistence-sdk
+description: Public API, SyncManager, Core Data and Realm stores, pod boundaries for iOS persistence
+---
+
+# Contentstack iOS Persistence SDK – Contentstack iOS Persistence
+
+## When to use
+
+- You change **`SyncManager`**, **`PersistenceModel`**, **`SyncPersistable`**, **`SyncProtocol`**, or store implementations
+- You edit **podspecs** or dependency ranges (`Contentstack`, `Realm`)
+- You need to explain how this library relates to the **Contentstack** iOS SDK and sync
+
+## Instructions
+
+### What this library owns
+
+- **Core framework** (`ContentstackPersistence/`): shared types and **`SyncManager`** orchestration; depends on **Contentstack** for stack/sync, not on Realm/Core Data directly in the base podspec.
+- **Core Data path** (`ContentstackPersistenceCoredata/` + `ContentstackPersistenceCoreData.podspec`): **`CoreDataStore`** and Core Data–backed persistence.
+- **Realm path** (`ContentstackPersistenceRealm/` + `ContentstackPersistenceRealm.podspec`): **`RealmStore`** and Realm-backed persistence; adds an explicit **Realm** dependency range in the podspec.
+
+### Public surface
+
+- Umbrella / public headers are declared per podspec (`s.public_header_files`); keep Objective-C headers stable for binary compatibility expectations in downstream apps.
+- **`SyncManager`** is the main integration point: constructed with a **Stack** (from Contentstack SDK) and a store conforming to the persistence abstraction (`CoreDataStore`, `RealmStore`, etc.).
+- **`PersistenceModel`** maps sync stack, assets, and entry types when customizing what gets persisted.
+
+### Boundaries
+
+- **In scope:** Local persistence adapters, sync callback handling, model mapping for offline storage.
+- **Out of scope:** Implementing REST/CDA calls here—that lives in **Contentstack**; this repo consumes **Stack** and sync flows from that SDK.
+
+### Versioning
+
+- Bump **`s.version`** consistently across podspecs when releasing; **`s.source`** `:tag` should match your git tagging convention (e.g. `v0.1.1`).
+- Subspecs depend on **`ContentstackPersistence`** with a matching semver range—keep those constraints coherent when you change the core.
+
+## References
+
+- [README.md](../../README.md) — integration examples (Objective-C and Swift)
+- [objc-swift-ios](../objc-swift-ios/SKILL.md)
+- [ios-persistence-platform](../ios-persistence-platform/SKILL.md)
+- [Contentstack iOS Persistence docs](https://www.contentstack.com/docs/guide/synchronization/using-realm-persistence-library-with-ios-sync-sdk)
+- [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/)

skills/dev-workflow/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: dev-workflow
+description: Branch policy, CI, and local build/test commands for contentstack-ios-persistence
+---
+
+# Dev workflow – Contentstack iOS Persistence
+
+## When to use
+
+- You are opening a PR, choosing a base branch, or interpreting CI failures
+- You need the canonical `pod install` / `xcodebuild` commands for this repo
+- You want release or versioning expectations (podspecs, tags)
+
+## Instructions
+
+### Branches and PRs
+
+- **Default branch workflow:** `.github/workflows/check-branch.yml` blocks merging into `master` unless the PR branch is `next`. For changes targeting `master`, open PRs **from** `next` as described in that workflow’s message.
+- Use **CODEOWNERS** for required reviewers when present.
+
+### Local development
+
+1. Install pods: `pod install` from the repo root (generates/updates `Pods/` and integrates with the workspace).
+2. Open **`ContentstackPersistence.xcworkspace`** (not the `.xcodeproj` alone) when working with CocoaPods.
+
+### Build and test
+
+- **Build:** `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -sdk iphonesimulator build`
+- **Test:** `xcodebuild -workspace ContentstackPersistence.xcworkspace -scheme ContentstackPersistence -destination 'platform=iOS Simulator,name=iPhone 16' test` — pick a simulator that exists on your Mac.
+
+### CI (GitHub Actions)
+
+- **Branch check:** `.github/workflows/check-branch.yml` — PRs to `master` from branches other than `next` fail by policy.
+- **SCA:** `.github/workflows/sca-scan.yml` — Snyk `snyk test` on PRs (requires `SNYK_TOKEN` in org secrets).
+- **Policy:** `.github/workflows/policy-scan.yml` — public repos: `SECURITY.md` and license file with current year.
+- **Issues:** `.github/workflows/issues-jira.yml` — Jira integration for issues.
+
+### Versioning and release hints
+
+- Three podspecs at repo root must stay aligned when you bump versions: `ContentstackPersistence.podspec`, `ContentstackPersistenceCoreData.podspec`, `ContentstackPersistenceRealm.podspec` (see `s.version` and `s.source` tag).
+- **Talisman:** `.talismanrc` may apply to pre-commit secret scanning; do not commit API keys or tokens.
+
+## References
+
+- [AGENTS.md](../../AGENTS.md)
+- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md)
+- [testing](../testing/SKILL.md)
+- [ios-persistence-platform](../ios-persistence-platform/SKILL.md)

skills/ios-persistence-platform/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: ios-persistence-platform
+description: CocoaPods, Xcode workspace, Realm vs Core Data, and iOS deployment for this repo
+---
+
+# iOS persistence platform – Contentstack iOS Persistence
+
+## When to use
+
+- You change **CocoaPods** integration (`Podfile`, `Podfile.lock`, podspecs)
+- You choose or explain **Realm** vs **Core Data** delivery paths
+- You adjust **iOS deployment target** or linker settings (`OTHER_LDFLAGS`, etc.)
+
+## Instructions
+
+### CocoaPods
+
+- **Install:** `pod install` from repo root; open **`ContentstackPersistence.xcworkspace`**.
+- **Consumable pods:** `ContentstackPersistence` (core), `ContentstackPersistenceCoreData`, `ContentstackPersistenceRealm` — see [README.md](../../README.md) for `Podfile` lines.
+- **Lockfile:** Commit `Podfile.lock` when dependency resolution should be reproducible for CI or the team (follow existing repo practice).
+
+### Realm vs Core Data
+
+- **Realm:** `ContentstackPersistenceRealm` pod; depends on **Realm** (see `ContentstackPersistenceRealm.podspec`); implementation in `ContentstackPersistenceRealm/`.
+- **Core Data:** `ContentstackPersistenceCoreData` pod; no Realm dependency; implementation in `ContentstackPersistenceCoredata/`.
+- **Core** pod `ContentstackPersistence` is shared; apps pick one persistence backend or structure their app module graph accordingly.
+
+### Xcode
+
+- **Scheme:** Use `ContentstackPersistence` for build/test of the main framework (scheme may be generated in Xcode if not checked in—create/share schemes if the team standardizes on committed schemes).
+- **SDK:** `iphonesimulator` for typical local builds; device builds when validating arm64/device-only issues.
+
+### Deployment target
+
+- Podspecs specify **`s.ios.deployment_target = '12.0'`** — keep podspecs aligned when raising the minimum iOS version.
+
+### Contentstack SDK
+
+- Base dependency on **Contentstack** iOS SDK with ranges in podspecs (`~> 3.12` core / Core Data, `~> 3.6` Realm podspec for historical range—verify compatibility when bumping).
+
+## References
+
+- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md)
+- [dev-workflow](../dev-workflow/SKILL.md)
+- [Example app (external)](https://github.com/contentstack/contentstack-ios-persistence-example)

skills/objc-swift-ios/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: objc-swift-ios
+description: Objective-C-first layout, headers, and Swift interop for this iOS persistence repo
+---
+
+# Objective-C / Swift & repo layout – Contentstack iOS Persistence
+
+## When to use
+
+- You add or rename `.h` / `.m` files under `ContentstackPersistence/`, `ContentstackPersistenceCoredata/`, or `ContentstackPersistenceRealm/`
+- You expose symbols to Swift consumers (`@import` / `import` patterns in README)
+- You align with existing naming and module structure
+
+## Instructions
+
+### Language
+
+- **Primary implementation language:** Objective-C (`.m` / `.h`).
+- **Swift:** Documented in [README.md](../../README.md) via module imports; keep public APIs Objective-C–friendly (`NS_SWIFT_NAME` only if you introduce names that need Swift polish—follow existing project style).
+
+### Layout (by folder)
+
+| Path | Role |
+| --- | --- |
+| `ContentstackPersistence/` | Core framework: `SyncManager`, `PersistenceModel`, protocols, umbrella `ContentstackPersistence.h` |
+| `ContentstackPersistenceCoredata/` | Core Data store implementation |
+| `ContentstackPersistenceRealm/` | Realm store implementation |
+| `ContentstackPersistenceTests/` | XCTest sources |
+
+### Headers and modules
+
+- Public API is driven by **`s.public_header_files`** in each podspec—new public headers must be listed there.
+- Keep umbrella / main header includes predictable; consumers may use `#import <Module/Module.h>` or `@import Module`.
+
+### Naming and style
+
+- Match existing patterns: Objective-C naming, file names aligned with class names (e.g. `SyncManager.h` / `SyncManager.m`).
+- Avoid drive-by reformatting unrelated code in the same change as feature work.
+
+## References
+
+- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md)
+- [testing](../testing/SKILL.md)

skills/testing/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: testing
+description: XCTest layout, simulator runs, and secrets policy for ContentstackPersistenceTests
+---
+
+# Testing – Contentstack iOS Persistence
+
+## When to use
+
+- You add or change tests under `ContentstackPersistenceTests/`
+- You run tests locally or debug CI test failures
+- You need guidance on credentials and fixtures
+
+## Instructions
+
+### Runner and location
+
+- **Framework:** XCTest (`ContentstackPersistenceTests.m` and future `*Tests.m` files).
+- **Target:** `ContentstackPersistenceTests` (xctest bundle `ContentstackPersistenceTests.xctest`).
+- **Run:** After `pod install`, use `xcodebuild` with scheme `ContentstackPersistence` and action `test`, with an iOS Simulator destination (see [AGENTS.md](../../AGENTS.md)).
+
+### Naming and structure
+
+- Test class inherits from `XCTestCase`; methods follow `- (void)test*` naming.
+- Prefer descriptive test names that state what is being verified (replace placeholder `testExample` when adding real coverage).
+
+### Credentials and data
+
+- **Do not** commit API keys, delivery tokens, or stack secrets to tests or repo files.
+- Prefer mocks, dependency injection at the store/sync boundaries, or local fixtures checked in without secrets.
+- If integration tests against a real stack are ever added, isolate them behind explicit schemes or skipped-by-default targets and load credentials from the environment or ignored local config—not from git.
+
+### Coverage
+
+- No shared coverage gate is defined in-repo; if the team adds Xcode coverage or a script, document the command in [dev-workflow](../dev-workflow/SKILL.md) and [AGENTS.md](../../AGENTS.md).
+
+## References
+
+- [dev-workflow](../dev-workflow/SKILL.md)
+- [contentstack-ios-persistence-sdk](../contentstack-ios-persistence-sdk/SKILL.md)