docs(DX-6049): add AGENTS.md, skills, and Cursor rules entry

.cursor/rules/README.md

@@ -1,37 +1,5 @@
-# Cursor Rules — `@contentstack/delivery-sdk`
+# Cursor (optional)
 
-Rules for **contentstack-typescript**: TypeScript **CDA** SDK built on **`@contentstack/core`**.
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
 
-## Rules overview
-
-| Rule | Role |
-|------|------|
-| [`dev-workflow.md`](dev-workflow.md) | Branch/PR, build, tests (`unit` / `api` / `browser`), e2e |
-| [`typescript.mdc`](typescript.mdc) | TS conventions, `src/`, `config/` |
-| [`contentstack-delivery-typescript.mdc`](contentstack-delivery-typescript.mdc) | **stack**, queries, cache, live preview, **core** integration |
-| [`testing.mdc`](testing.mdc) | Jest suites, **jest.setup.ts**, env, Playwright |
-| [`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` |
-| **`src/`** | `typescript.mdc` + `contentstack-delivery-typescript.mdc` |
-| **`test/**`** | `testing.mdc` |
-| **Rollup / TS config** | `typescript.mdc` |
-
-## Quick reference
-
-| File | `alwaysApply` | Globs (summary) |
-|------|---------------|-----------------|
-| `dev-workflow.md` | no | `**/*.ts`, `**/*.mjs`, `**/*.json` |
-| `typescript.mdc` | no | `src/**/*.ts`, `config/**/*.ts`, `jest.config.ts`, `jest.config.browser.ts`, `jest.setup.ts` |
-| `contentstack-delivery-typescript.mdc` | no | `src/**/*.ts` |
-| `testing.mdc` | no | `test/**/*.ts`, `playwright.config.ts` |
-| `code-review.mdc` | **yes** | — |
-
-## Skills
-
-- [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

AGENTS.md

@@ -1,59 +1,45 @@
-# AGENTS.md — AI / automation context
+# Contentstack TypeScript Delivery SDK – Agent guide
 
-## Project
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-| | |
-|---|---|
-| **Name** | **`@contentstack/delivery-sdk`** (npm) — **Contentstack TypeScript Content Delivery SDK** |
-| **Purpose** | TypeScript client for the **Content Delivery API (CDA)**: stacks, entries, assets, queries, sync, live preview, cache. Built on **`@contentstack/core`** (**Axios** HTTP + retry helpers) and **`@contentstack/utils`**. |
-| **Repository** | [contentstack/contentstack-typescript](https://github.com/contentstack/contentstack-typescript.git) |
+## What this repo is
 
-## Tech stack
+| Field | Detail |
+|--------|--------|
+| **Name:** | [contentstack-typescript](https://github.com/contentstack/contentstack-typescript) (`@contentstack/delivery-sdk`) |
+| **Purpose:** | TypeScript/JavaScript Content Delivery SDK for fetching and working with stack content in Node and browsers. |
+| **Out of scope:** | Not the Management API or CLI; use the appropriate Contentstack tools for non-delivery workflows. |
+
+## Tech stack (at a glance)
 
 | Area | Details |
 |------|---------|
-| **Language** | **TypeScript**, **ES modules** (`"type": "module"`) |
-| **Runtime** | Node **>= 18** (`package.json` `engines`) |
-| **Build** | **Rollup** (`npm run build:rollup`) + **`tsc`** declarations (`config/tsconfig.decl-esm.json`) → **`dist/modern/`** |
-| **Tests** | **Jest** + **ts-jest**: **`test/unit`**, **`test/api`**, **`test/browser`**; **Playwright** e2e (`test/e2e`, `npm run test:e2e`) |
-| **Lint** | **ESLint** (`.eslintrc.json`) |
-
-## Source layout
-
-| Path | Role |
-|------|------|
-| `src/stack/contentstack.ts` | **`stack(config)`** factory — wires **`httpClient`** from **`@contentstack/core`**, region/host, live preview |
-| `src/stack/stack.ts` | **Stack** class |
-| `src/query/**` | Queries (entry, asset, taxonomy, content type, …) |
-| `src/entries/**`, `src/assets/**`, `src/sync/**`, `src/cache/**` | Domain modules |
-| `src/common/**` | Types, utils, errors, pagination |
-| `src/index.ts` | Public package exports |
-| `test/utils/stack-instance.ts` | **`stackInstance()`** — loads **dotenv**, **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`**, optional live-preview vars |
-
-## Common commands
-
-```bash
-npm install
-npm run build
-npm run test:unit      # jest ./test/unit
-npm run test:api       # live API — needs .env (see stack-instance)
-npm run test:browser
-npm run test:e2e       # Playwright (builds browser bundle first)
-npm run test:all       # unit + browser + api
-```
-
-## Environment variables (API / integration tests)
-
-Loaded via **`dotenv`** in **`test/utils/stack-instance.ts`**:
-
-- **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`** — stack connection
-- Optional: **`PREVIEW_TOKEN`**, **`LIVE_PREVIEW_HOST`** for live preview tests
-
-Do not commit secrets.
-
-## 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://www.contentstack.com/docs/developers/apis/content-delivery-api/).
+| Language | TypeScript (`typescript` in `package.json`); Node **≥ 18** |
+| Build | Rollup (`rollup -c`), declaration emit (`config/tsconfig.decl-esm.json`) → `dist/modern/` |
+| Tests | Jest: `test/unit`, `test/api`, browser config; Playwright for e2e (`test/e2e`); bundler smoke tests under `test/bundlers/` |
+| Lint / coverage | No root `lint` script—use `npm run validate:all` and `.github/workflows/coverage-check.yml` for quality gates |
+| CI | `.github/workflows/coverage-check.yml`, `check-branch.yml`, `sca-scan.yml`, `policy-scan.yml`, `npm-publish.yml` |
+
+## Commands (quick reference)
+
+| Command type | Command |
+|--------------|---------|
+| Build | `npm run build` |
+| Test (common) | `npm run test:unit` / `npm run test:api` / `npm run test:all` |
+| Validate | `npm run validate:all` |
+| Full CI-style suite | `npm run test:cicd` or `npm run test:cicd:no-browser` (see `package.json`) |
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, npm scripts, prerelease |
+| **Delivery SDK** | [`skills/contentstack-delivery-typescript/SKILL.md`](skills/contentstack-delivery-typescript/SKILL.md) | Public API, stack client, `@contentstack/core` usage |
+| **TypeScript & layout** | [`skills/typescript/SKILL.md`](skills/typescript/SKILL.md) | `src/`, Rollup outputs, modern CJS/ESM |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Jest, API tests, Playwright, bundler matrix |
+| **Build & platform** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | Rollup, browser safety, bundler validation |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist for SDK changes |
+
+## 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.

skills/code-review/SKILL.md

@@ -1,19 +1,27 @@
 ---
 name: code-review
-description: PR review for @contentstack/delivery-sdk — public API, StackConfig, core alignment, tests.
+description: Use when reviewing PRs for the TypeScript Delivery SDK—API, tests, bundler impact, semver.
 ---
 
-# Code review — `@contentstack/delivery-sdk`
+# Code review – contentstack-typescript
 
-## Checklist
+## When to use
 
-- [ ] **API:** New or changed **`stack()`** / **Stack** / query methods documented; exports updated in **`src/index.ts`**.
-- [ ] **Types:** **StackConfig** and public interfaces remain consistent with **`dist/modern/*.d.ts`** after build.
-- [ ] **@contentstack/core:** Version or API changes validated in **`src/stack/contentstack.ts`** (interceptors, **httpClient** options).
-- [ ] **Tests:** **`test:unit`** passes; add/extend **`test/api`** when integration behavior changes; browser/e2e if relevant.
-- [ ] **Secrets:** No tokens in repo; **stack-instance** env vars only for local CI secrets store.
+- Reviewing SDK features, fixes, or dependency upgrades
+- Assessing risk of a change to browser/Node consumers
 
-## References
+## Instructions
 
-- `.cursor/rules/code-review.mdc`
-- `.cursor/rules/dev-workflow.md`
+### Checklist
+
+- **Semver**: Public API or default behavior change flagged for major/minor/patch appropriately.
+- **Core/utils**: Coordinated version bumps for `@contentstack/core` and `@contentstack/utils` when needed.
+- **Tests**: Unit + relevant API/browser/bundler coverage for the change.
+- **Build**: `npm run build` succeeds; consider `npm run validate:all` for packaging-sensitive edits.
+- **Docs**: README or type docs updated for user-visible changes.
+
+### Severity hints
+
+- **Blocker**: Broken `exports`, failing CI, or security issues in dependencies.
+- **Major**: Missing tests for cross-bundler or browser regressions.
+- **Minor**: Internal refactors with full green matrix.