contentstack · cs-raj · Apr 7, 2026
@@ -0,0 +1,8 @@
+# Cursor (optional)
+
+**Cursor** users:
+
+- Start at **[`AGENTS.md`](../../AGENTS.md)** — project entry point and commands.
+- Skills index and `references/` layout: **[`skills/README.md`](../../skills/README.md)**.
+
+All conventions live in **`skills/*/SKILL.md`** and linked **`skills/*/references/*.md`**. This folder only points contributors to those paths so editor-specific config does not duplicate the canonical docs.
@@ -28,3 +28,5 @@ api_referece/*
 *.html
 *.cobertura.xml
 integration-test-report_*.html
+*.zip
+.trx
@@ -0,0 +1,52 @@
+# Contentstack Management .NET SDK – 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/contentstack-management-dotnet](https://github.com/contentstack/contentstack-management-dotnet) |
+| **Purpose:** | .NET SDK for the [Content Management API (CMA)](https://www.contentstack.com/docs/developers/apis/content-management-api/)—manage stacks, content types, entries, assets, and related resources. |
+| **Out of scope (if any):** | Content **delivery** to end users should use the Content Delivery API and its SDKs, not this package. This repo does not implement the CDA. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| ---- | ------- |
+| **Language** | C# 8.0, nullable reference types enabled (`LangVersion` in core project). |
+| **Build** | .NET SDK; main solution [`Contentstack.Management.Core.sln`](Contentstack.Management.Core.sln). Core library targets `netstandard2.0` (and `net471` / `net472` on Windows—see [`skills/framework/SKILL.md`](skills/framework/SKILL.md)). |
+| **Tests** | MSTest; test projects target `net7.0`. Unit tests: [`Contentstack.Management.Core.Unit.Tests/`](Contentstack.Management.Core.Unit.Tests/). Integration tests: [`Contentstack.Management.Core.Tests/`](Contentstack.Management.Core.Tests/) (includes `IntegrationTest/`). |
+| **Lint / coverage** | No repo-wide `dotnet format` / lint script at root. Rely on **.NET SDK analyzers** and IDE analysis. Tests use **coverlet** (`XPlat code coverage`) when run as in CI. |
+| **Other** | NuGet packages: `contentstack.management.csharp` (core), `contentstack.management.aspnetcore` (ASP.NET Core helpers). Assembly signing via `CSManagementSDK.snk`. |
+
+## Commands (quick reference)
+
+| Command type | Command |
+| ------------ | ------- |
+| **Build** | `dotnet build Contentstack.Management.Core.sln` |
+| **Test (CI-parity, unit)** | `sh ./Scripts/run-unit-test-case.sh` — runs `dotnet test` on [`Contentstack.Management.Core.Unit.Tests/Contentstack.Management.Core.Unit.Tests.csproj`](Contentstack.Management.Core.Unit.Tests/Contentstack.Management.Core.Unit.Tests.csproj) with TRX logger and coverlet. |
+| **Test (integration)** | `dotnet test Contentstack.Management.Core.Tests/Contentstack.Management.Core.Tests.csproj` — requires local `appsettings.json` with credentials (see [`skills/testing/SKILL.md`](skills/testing/SKILL.md)). |
+| **Pack (release)** | `dotnet pack -c Release -o out` (as in [`.github/workflows/nuget-publish.yml`](.github/workflows/nuget-publish.yml)). |
+
+**CI:** [`.github/workflows/unit-test.yml`](.github/workflows/unit-test.yml) (unit tests on PR/push). **Branches:** PRs normally target **`development`**; **`main`** is for **hotfixes**. PRs **into `main`** must come from **`staging`** per [`.github/workflows/check-branch.yml`](.github/workflows/check-branch.yml).
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| ----- | ---- | -------------- |
+| Dev workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, scripts, when to run which tests. |
+| SDK (CMA) | [`skills/contentstack-management-dotnet-sdk/SKILL.md`](skills/contentstack-management-dotnet-sdk/SKILL.md) | Public API, auth, package boundaries. |
+| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | MSTest layout, unit vs integration, credentials, coverage. |
+| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR expectations and checklist. |
+| Framework / platform | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | TFMs, signing, NuGet, HTTP pipeline overview. |
+| C# style | [`skills/csharp-style/SKILL.md`](skills/csharp-style/SKILL.md) | Language and layout conventions for this repo. |
+| HTTP pipeline (retries) | [`skills/http-pipeline/SKILL.md`](skills/http-pipeline/SKILL.md) | Handlers, retry policy, pipeline behavior. |
+| ASP.NET Core integration | [`skills/aspnetcore-integration/SKILL.md`](skills/aspnetcore-integration/SKILL.md) | `contentstack.management.aspnetcore` package and DI. |
+| Documentation (DocFX) | [`skills/documentation/SKILL.md`](skills/documentation/SKILL.md) | API docs under `docfx_project/`. |
+
+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) points to **`AGENTS.md`** and **`skills/`**—same docs as everyone else; no duplicated prose in `.cursor`.
@@ -0,0 +1,39 @@
+# Skills – Contentstack Management .NET SDK
+
+Source of truth for detailed guidance. Read [`AGENTS.md`](../AGENTS.md) first, then open the skill that matches your task.
+
+## Project context
+
+| Area | This repo (CMA SDK) |
+| ---- | ------------------- |
+| **API** | [Content Management API (CMA)](https://www.contentstack.com/docs/developers/apis/content-management-api/) — not the Content Delivery API (CDA). |
+| **Packages** | `contentstack.management.csharp` (core), `contentstack.management.aspnetcore` (DI helpers). |
+| **HTTP** | `HttpClient` through [`ContentstackClient`](../Contentstack.Management.Core/ContentstackClient.cs) → runtime pipeline (`HttpHandler`, `RetryHandler`). |
+| **Language / tests** | C# 8, nullable enabled. **MSTest** on **net7.0**; unit tests use **Moq** and **AutoFixture** where existing tests do. |
+
+## How to use these skills
+
+- **In the repo:** open `skills/<folder>/SKILL.md` for the topic you need. Longer templates and checklists live under `skills/<folder>/references/*.md` where linked.
+- **In Cursor / other AI chats:** reference a skill by path, e.g. `skills/http-pipeline/SKILL.md` or `@skills/http-pipeline` if your tooling resolves that alias to this folder.
+
+## Example prompts
+
+- “Add a new CMA endpoint wrapper following `skills/contentstack-management-dotnet-sdk/SKILL.md` and `references/cma-architecture.md`.”
+- “Adjust retry behavior for 429 responses using `skills/http-pipeline/` and update unit tests under `Contentstack.Management.Core.Unit.Tests/Runtime/Pipeline/`.”
+- “Write a unit test with MSTest + Moq following `skills/testing/references/mstest-patterns.md`.”
+
+## When to use which skill
+
+| Skill folder | Use when |
+| ------------ | -------- |
+| [`dev-workflow/`](dev-workflow/) | Git branches, CI workflows, running build/test scripts, release/NuGet flow. |
+| [`contentstack-management-dotnet-sdk/`](contentstack-management-dotnet-sdk/) | `ContentstackClient`, options, authentication, public API and package boundaries. |
+| [`testing/`](testing/) | Writing or running unit/integration tests, MSTest, coverlet, local credentials. |
+| [`code-review/`](code-review/) | Preparing or reviewing a PR against this repository. |
+| [`framework/`](framework/) | Target frameworks, signing, NuGet packaging, OS-specific builds, high-level HTTP/runtime stack. |
+| [`csharp-style/`](csharp-style/) | C# language version, nullable usage, naming and folder layout consistent with the repo. |
+| [`http-pipeline/`](http-pipeline/) | Changing `HttpHandler`, `RetryHandler`, retry policy, or pipeline ordering. |
+| [`aspnetcore-integration/`](aspnetcore-integration/) | `Contentstack.Management.ASPNETCore` package, `IHttpClientFactory`, DI registration. |
+| [`documentation/`](documentation/) | Building or updating DocFX API documentation under `docfx_project/`. |
+
+Each folder contains **`SKILL.md`** with YAML frontmatter (`name`, `description`). **Deep dives:** see the **Quick reference** line at the top of each `SKILL.md` for links to `references/`.
@@ -0,0 +1,36 @@
+---
+name: aspnetcore-integration
+description: Use for the contentstack.management.aspnetcore package, HttpClient/DI registration with ASP.NET Core.
+---
+
+# ASP.NET Core integration – Contentstack Management .NET SDK
+
+## When to use
+
+- Changing [`Contentstack.Management.ASPNETCore/`](../../Contentstack.Management.ASPNETCore/) or the NuGet package **`contentstack.management.aspnetcore`**.
+- Registering `ContentstackClient` with `IHttpClientFactory` / `IServiceCollection`.
+
+## Instructions
+
+### Package
+
+- **Package ID:** `contentstack.management.aspnetcore`
+- **Target:** `netstandard2.1`
+- **Project:** [`contentstack.management.aspnetcore.csproj`](../../Contentstack.Management.ASPNETCore/contentstack.management.aspnetcore.csproj)
+
+### Registration APIs
+
+- [`ServiceCollectionExtensions`](../../Contentstack.Management.ASPNETCore/ServiceCollectionExtensions.cs) in namespace `Microsoft.Extensions.DependencyInjection`:
+  - `AddContentstackClient(IServiceCollection, ContentstackClientOptions)` / `TryAddContentstackClient` — extend here when wiring options-based registration; keep behavior aligned with DI conventions.
+  - `AddContentstackClient(IServiceCollection, Action<HttpClient>)` — registers `ContentstackClient` with **`AddHttpClient<ContentstackClient>`** for typed client configuration.
+
+When extending DI support, align with Microsoft.Extensions.DependencyInjection and `Microsoft.Extensions.Http` patterns already referenced in the project file.
+
+### Core dependency
+
+- The ASP.NET Core project references the core management package; public types come from [`Contentstack.Management.Core`](../../Contentstack.Management.Core/).
+
+## References
+
+- [`../contentstack-management-dotnet-sdk/SKILL.md`](../contentstack-management-dotnet-sdk/SKILL.md) — core client and options.
+- [`../framework/SKILL.md`](../framework/SKILL.md) — NuGet and TFMs.
@@ -0,0 +1,44 @@
+---
+name: code-review
+description: Use when reviewing or preparing a pull request for contentstack-management-dotnet.
+---
+
+# Code review – Contentstack Management .NET SDK
+
+**Deep dive:** [`references/checklist.md`](references/checklist.md) (copy-paste PR checklist sections).
+
+## When to use
+
+- Before requesting review or merging a PR.
+- When auditing changes for API safety, tests, and repo policies.
+
+## Instructions
+
+### Branch and merge expectations
+
+- **Typical PRs** should target **`development`**. Use **`main`** as the base branch only for **hotfixes**.
+- **When the base is `main`:** only PRs from **`staging`** are allowed (enforced by [`.github/workflows/check-branch.yml`](../../.github/workflows/check-branch.yml)). Confirm head/base match team intent before approving.
+
+### Summary checklist
+
+- **Purpose:** Change matches the ticket/PR description; no unrelated refactors.
+- **Tests:** Unit tests updated or added for behavior changes; run `sh ./Scripts/run-unit-test-case.sh` locally for core changes. Integration tests only when behavior depends on live API—coordinate credentials.
+- **API compatibility:** Public surface (`ContentstackClient`, options, models) changes are intentional and versioned appropriately; avoid breaking changes without major bump and changelog.
+- **Security:** No secrets, tokens, or keys in source or commits; `appsettings.json` with real data must not be committed.
+- **Signing:** If assembly signing is affected, confirm `CSManagementSDK.snk` usage matches [`../framework/SKILL.md`](../framework/SKILL.md).
+- **Style:** Follow [`../csharp-style/SKILL.md`](../csharp-style/SKILL.md); match surrounding code.
+- **Documentation:** User-visible behavior changes reflected in `README.md` or package release notes when needed.
+
+For markdown blocks to paste into PRs, use [`references/checklist.md`](references/checklist.md).
+
+### Severity (optional labels)
+
+- **Blocker:** Build or CI broken; security issue; violates branch policy.
+- **Major:** Missing tests for risky logic; breaking API without process.
+- **Minor:** Naming nits, non-user-facing cleanup.
+
+## References
+
+- [`references/checklist.md`](references/checklist.md) — detailed PR checklist.
+- [`../dev-workflow/SKILL.md`](../dev-workflow/SKILL.md) — CI and branches.
+- [`../contentstack-management-dotnet-sdk/SKILL.md`](../contentstack-management-dotnet-sdk/SKILL.md) — API boundaries.
@@ -0,0 +1,55 @@
+# PR review checklist (CMA Management SDK)
+
+Copy sections into a PR comment when useful. This checklist is for **this** repo (`HttpClient` + pipeline + MSTest), **not** the Content Delivery .NET SDK.
+
+## Branch policy
+
+```markdown
+- [ ] **Default:** PR targets **`development`** unless this is a documented **hotfix** to **`main`**
+- [ ] If base is **`main`**: head branch is **`staging`** (see `.github/workflows/check-branch.yml`)
+```
+
+## Breaking changes
+
+```markdown
+- [ ] No public method/property removed or narrowed without deprecation / major version plan
+- [ ] `JsonProperty` / JSON names for API-facing models unchanged unless intentional and documented
+- [ ] New required `ContentstackClientOptions` fields have safe defaults or are optional
+- [ ] Strong naming: assembly signing still consistent if keys or `csproj` changed
+```
+
+## HTTP and pipeline
+
+```markdown
+- [ ] New or changed HTTP calls go through existing client/pipeline (`ContentstackClient` → `IContentstackService` → pipeline), not ad-hoc `HttpClient` usage inside services without justification
+- [ ] Retry-sensitive changes reviewed alongside `RetryHandler` / `DefaultRetryPolicy` and unit tests under `Contentstack.Management.Core.Unit.Tests/Runtime/Pipeline/`
+- [ ] Headers, query params, and path segments align with CMA docs; no hardcoded production URLs where options.Host should be used
+```
+
+## Services and query API
+
+```markdown
+- [ ] `IContentstackService` implementations set `ResourcePath`, `HttpMethod`, `Parameters` / `QueryResources` / `PathResources` / `Content` consistently with sibling services
+- [ ] New fluent `Query` methods only add to `ParameterCollection` with correct API parameter names
+```
+
+## Tests
+
+```markdown
+- [ ] Unit tests use MSTest; `sh ./Scripts/run-unit-test-case.sh` passes for core changes
+- [ ] Integration tests only when needed; no secrets committed (`appsettings.json` stays local)
+```
+
+## Security and hygiene
+
+```markdown
+- [ ] No API keys, tokens, or passwords in source or test data checked into git
+- [ ] OAuth / token handling does not log secrets
+```
+
+## Documentation
+
+```markdown
+- [ ] User-visible behavior reflected in `README.md` or release notes when appropriate
+- [ ] `skills/` or `references/` updated if agent/contributor workflow changed
+```
@@ -0,0 +1,57 @@
+---
+name: contentstack-management-dotnet-sdk
+description: Use when changing or using the CMA client API, authentication, or NuGet package surface for Contentstack.Management.Core.
+---
+
+# Contentstack Management .NET SDK (CMA)
+
+**Deep dive:** [`references/cma-architecture.md`](references/cma-architecture.md) (request flow, `IContentstackService`), [`references/query-and-parameters.md`](references/query-and-parameters.md) (fluent `Query`, `ParameterCollection`).
+
+## When to use
+
+- Adding or changing `ContentstackClient` behavior, options, or service entry points.
+- Documenting how consumers authenticate (management token, authtoken, login).
+- Reviewing breaking vs compatible changes for the NuGet package `contentstack.management.csharp`.
+
+## Instructions
+
+### Packages and entry points
+
+| Package ID | Project | Role |
+| ---------- | ------- | ---- |
+| `contentstack.management.csharp` | [`Contentstack.Management.Core/`](../../Contentstack.Management.Core/) | Main SDK; `ContentstackClient`, models, services. |
+| `contentstack.management.aspnetcore` | [`Contentstack.Management.ASPNETCore/`](../../Contentstack.Management.ASPNETCore/) | ASP.NET Core registration helpers; see [`../aspnetcore-integration/SKILL.md`](../aspnetcore-integration/SKILL.md). |
+
+- Primary type: [`ContentstackClient`](../../Contentstack.Management.Core/ContentstackClient.cs) (`IContentstackClient`).
+- Configuration: [`ContentstackClientOptions`](../../Contentstack.Management.Core/ContentstackClientOptions.cs) (and related options types).
+
+### Authentication (high level)
+
+- **Management token:** stack-scoped token; typical pattern `client.Stack(apiKey, managementToken)` per product docs.
+- **Authtoken:** user/session token on the client options.
+- **Login with credentials:** `ContentstackClient.Login` / `LoginAsync` with `NetworkCredential` (see root [`README.md`](../../README.md) examples).
+
+OAuth-related code lives under [`Services/OAuth/`](../../Contentstack.Management.Core/Services/OAuth/), [`OAuthHandler.cs`](../../Contentstack.Management.Core/OAuthHandler.cs), and [`Utils/PkceHelper.cs`](../../Contentstack.Management.Core/Utils/PkceHelper.cs). Prefer small, testable changes; preserve existing public contracts unless doing a major version bump.
+
+### Serialization and models
+
+- JSON serialization and converters are configured in `ContentstackClient` (e.g. custom `JsonConverter` types for fields and nodes).
+- Domain models live under [`Models/`](../../Contentstack.Management.Core/Models/). Follow existing patterns when adding types.
+
+### Errors
+
+- Exceptions and error mapping: [`Exceptions/`](../../Contentstack.Management.Core/Exceptions/). Keep messages and HTTP status handling consistent with existing patterns.
+
+### Integration boundaries
+
+- The SDK talks to Contentstack **Management** HTTP APIs. Do not confuse with Delivery API clients.
+- HTTP behavior (retries, handlers) is documented under [`../framework/SKILL.md`](../framework/SKILL.md) and [`../http-pipeline/SKILL.md`](../http-pipeline/SKILL.md).
+
+## References
+
+- [`references/cma-architecture.md`](references/cma-architecture.md) — architecture and invocation flow.
+- [`references/query-and-parameters.md`](references/query-and-parameters.md) — fluent query API.
+- [`../framework/SKILL.md`](../framework/SKILL.md) — TFMs, NuGet, pipeline overview.
+- [`../http-pipeline/SKILL.md`](../http-pipeline/SKILL.md) — retries and handlers.
+- [`../csharp-style/SKILL.md`](../csharp-style/SKILL.md) — C# conventions.
+- [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/) (official docs).
-Original file line number
+Diff line change
@@ Expand Up / @@ -28,3 +28,5 @@ api_referece/* @@
     *.html
     *.cobertura.xml
     integration-test-report_*.html
+    *.zip
+    .trx