contentstack · cs-raj · Apr 20, 2026 · Apr 19, 2026
@@ -1,19 +1,5 @@
-# Cursor rules for `@contentstack/types-generator`
+# Cursor (optional)
 
-This folder contains project-specific rules for AI assistants and developers. Each file lists its scope in YAML frontmatter (`description`, `globs`, `alwaysApply`).
-
-
-| Rule file                                                      | `alwaysApply` | Globs                                                   | When it applies                                                   | Related skill                                                                  |
-| -------------------------------------------------------------- | ------------- | ------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| [dev-workflow.mdc](dev-workflow.mdc)                           | No            | `package.json`, `package-lock.json`, `.github/workflows/**/*`, `jest.config.js`, `tsup.config.ts`, `AGENTS.md` | Branch strategy, build/test commands, PR and release expectations | [testing](../../skills/testing/SKILL.md), [code-review](../../skills/code-review/SKILL.md) |
-| [typescript.mdc](typescript.mdc)                               | No            | `src/**/*.ts`, `tests/**/*.ts`                          | Editing or adding TypeScript in this package                      | [typescript-types-generator](../../skills/typescript-types-generator/SKILL.md) |
-| [contentstack-delivery-cda.mdc](contentstack-delivery-cda.mdc) | No            | `src/sdk/**`, `src/generateTS/**`, `src/graphqlTS/**`   | Delivery SDK, regions, stack config, GraphQL introspection/axios  | [typescript-types-generator](../../skills/typescript-types-generator/SKILL.md) |
-| [testing.mdc](testing.mdc)                                     | No            | `tests/**`, `jest.config.js`                            | Writing or running Jest tests, env for live tests                 | [testing](../../skills/testing/SKILL.md)                                       |
-| [code-review.mdc](code-review.mdc)                             | **Yes**       | —                                                       | Every change: API docs, compatibility, errors, security, tests    | [code-review](../../skills/code-review/SKILL.md)                               |
-
-
-## Referencing rules in Cursor
-
-- Use **@** in chat and pick a rule file (e.g. `@contentstack-delivery-cda`, `@dev-workflow`) to focus the model on Delivery/GraphQL or workflow context.
-- Rules with `alwaysApply: true` are included automatically; others apply when matching files are in context or when @-mentioned.
+**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.
@@ -3,15 +3,17 @@ fileignoreconfig:
     ignore_detectors:
       - filecontent
   - filename: package-lock.json
-    checksum: d392a5bf70cad2cb90afaf284410f580e359afe4f1a0a970a6f6061aee7c821c
-  - filename: .cursor/rules/testing.mdc
-    checksum: a3768ed70d1fa61e73d1838efbc3066859dd5dfce3fbefe40fb6c23800679a43
-  - filename: skills/README.md
-    checksum: ae09bf77a43f81f76a06f23ae2b2cbb1e81c490a66cf1b4e7df4e7142e22b5f5
+    checksum: 6a45ae66e7c4c62a43e40cfec58ab3c8fff37f04b02339e8019dd1ac503da995
   - filename: AGENTS.md
-    checksum: 6ff4b2c6957f75f85f6afd188cc09af21ac9c90f05f87e4198674302b74bb021
+    checksum: 93ded6952359760204f6235b0a29de9e4f594323326971a5cae0ee07ee9a822e
+  - filename: skills/README.md
+    checksum: 33e44991db811244b3ea9abd4be5eaafada3c9e6a7f3f55542aaf1be480d19a2
+  - filename: skills/dev-workflow/SKILL.md
+    checksum: f5b4a18948f0cec6c8a391d946670313fce7e998268677f9be12241c09e9558f
   - filename: skills/testing/SKILL.md
-    checksum: 858b4a830e74a0e90fe2f1097b4480a5eed513cdd88ba2646087399423ddee00
+    checksum: 5acca5b3e5a6871237b9775f855e81f01b300d591c3b5d6677d79426021e5c7b
   - filename: skills/typescript-types-generator/SKILL.md
-    checksum: aaa97f6eb31a66221ceedc7e5e965a9b13d33358a350dbfb3034014ece0c3e6c
+    checksum: 141c31039cdec5f1b0ba689a979292103e84da6e4862e878ee2e1384e3ea6fcd
+  - filename: skills/code-review/SKILL.md
+    checksum: 1b65b3ed25618cfc453b167d1b149348c0900f4721da3b24c8d847b7b1885f61
 version: "1.0"
@@ -1,49 +1,50 @@
-# `@contentstack/types-generator`
+# @contentstack/types-generator – Agent guide
 
-**Purpose:** Library for generating TypeScript type definitions from Contentstack stack content types (via the Delivery SDK) and from GraphQL schema (introspection over the Contentstack GraphQL endpoint).
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-- **Repository:** [github.com/contentstack/types-generator](https://github.com/contentstack/types-generator)
-- **Homepage:** [https://github.com/contentstack/types-generator](https://github.com/contentstack/types-generator)
+## What this repo is
 
-## Tech stack
-
-| Area | Details |
+| Field | Detail |
 | --- | --- |
-| Language | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) |
-| Runtime | Node (CI on **18.x** and **20.x**; release workflow uses **22.x**) |
-| Build | **tsup** → `dist/` ([tsup.config.ts](tsup.config.ts)): entries `index` ([src/index.ts](src/index.ts)), `web` ([src/web.ts](src/web.ts)) |
-| Tests | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)); `dotenv/config` in setup |
-| Main dependencies | `@contentstack/delivery-sdk`, `axios`, `@gql2ts/from-schema`, `lodash`, `async`, `prettier` |
-
-This package targets **Content Delivery (CDA)** and **GraphQL** only—not the Management API (CMA).
+| **Name:** | [contentstack/types-generator](https://github.com/contentstack/types-generator) |
+| **Purpose:** | Library that generates TypeScript types from Contentstack stack content types (Delivery SDK) and from GraphQL schema (introspection). |
+| **Out of scope (if any):** | **Management API (CMA)** client behavior—this package targets **CDA** and **GraphQL** only. |
 
-## Public API and source layout
+## Tech stack (at a glance)
 
-- **Package entry:** `main` / `module` / `types` point to `./dist/*` (see [package.json](package.json)).
-- **Exports:** `generateTS`, `graphqlTS`, and related symbols from [src/index.ts](src/index.ts) (re-exports from [src/generateTS/](src/generateTS/) and [src/graphqlTS/](src/graphqlTS/)).
-- **Key paths:** [src/sdk/](src/sdk/) (Delivery SDK wiring), [src/types/](src/types/), [src/format/](src/format/), [src/logger/](src/logger/), [src/constants/](src/constants/).
+| Area | Details |
+| --- | --- |
+| **Language** | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) |
+| **Build** | **tsup** → `dist/` ([tsup.config.ts](tsup.config.ts)); entries include [src/index.ts](src/index.ts), [src/web.ts](src/web.ts) |
+| **Tests** | Jest + ts-jest ([jest.config.js](jest.config.js)); `dotenv/config` in setup |
+| **Lint / coverage** | No ESLint script; rely on TypeScript strictness and project conventions |
+| **Other** | `@contentstack/delivery-sdk`, `axios`, `@gql2ts/from-schema`, `lodash`, `async`, `prettier` |
 
-## Common commands
+## Commands (quick reference)
 
-| Command | Purpose |
+| Command type | Command |
 | --- | --- |
-| `npm run build` | Run `tsup` (also runs on `npm run prepare`) |
-| `npm test` | Jest with `--testPathPattern=tests` and `NODE_OPTIONS=--experimental-vm-modules` |
-| `npm run test:unit:report:json` | Unit tests under `tests/unit` with coverage and JSON reports (used in CI) |
+| **Build** | `npm run build` |
+| **Test** | `npm test` |
+| **Lint** | _(not configured)_ |
 
-There is **no ESLint** script in this package; rely on TypeScript strictness and project conventions.
+CI: [.github/workflows/node.js.yml](.github/workflows/node.js.yml); release: [.github/workflows/release.yml](.github/workflows/release.yml).
 
 ## Credentials and integration tests
 
-Integration tests need a live stack. Set a **`.env`** at the repo root (see integration tests under `tests/integration/`) or export variables in your shell. Typical names:
+Set a **`.env`** at the repo root or export variables (see `tests/integration/`). Typical names: `TOKEN`, `APIKEY`, `ENVIRONMENT`, `REGION`, `TOKENTYPE`, `BRANCH`. CI injects secrets including `TOKEN_WITH_NO_CT` and `APIKEY_WITH_NO_CT` where needed.
 
-`TOKEN`, `APIKEY`, `ENVIRONMENT`, `REGION`, `TOKENTYPE`, `BRANCH`
+## Where the documentation lives: skills
 
-CI injects these from GitHub Actions secrets (see [.github/workflows/node.js.yml](.github/workflows/node.js.yml)), including `TOKEN_WITH_NO_CT` and `APIKEY_WITH_NO_CT` where tests require them.
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Development workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, CI, build/test, PRs, releases |
+| TypeScript types generator | [skills/typescript-types-generator/SKILL.md](skills/typescript-types-generator/SKILL.md) | `generateTS` vs `graphqlTS`, SDK and GraphQL behavior |
+| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Jest layout, `.env`, fixtures |
+| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist, terminology, semver |
 
----
+An index with “when to use” hints is in [skills/README.md](skills/README.md).
 
-## AI guidance index
+## Using Cursor (optional)
 
-- [Cursor rules (overview)](.cursor/rules/README.md) — when each rule applies and how to reference it.
-- [Skills index](skills/README.md) — deeper checklists and package mental model.
+If you use **Cursor**, [.cursor/rules/README.md](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.
@@ -1,11 +1,16 @@
-# Skills for `@contentstack/types-generator`
+# Skills – @contentstack/types-generator
 
-Short index of deeper guidance (use alongside [AGENTS.md](../AGENTS.md) and [`.cursor/rules/`](../.cursor/rules/README.md)).
+Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task.
 
-| Skill | When to use |
+## When to use which skill
+
+| Skill folder | Use when |
 | --- | --- |
-| [code-review](code-review/SKILL.md) | Preparing or reviewing a PR: API docs, compatibility, errors, security, tests, Delivery vs Management terminology. |
-| [testing](testing/SKILL.md) | Running Jest, unit vs integration layout, `.env` and CI secrets, content-type fixtures. |
-| [typescript-types-generator](typescript-types-generator/SKILL.md) | Understanding `generateTS` vs `graphqlTS`, main modules, and where to change behavior. |
+| [dev-workflow](dev-workflow/SKILL.md) | Branches, CI, build/test, PR and release |
+| [typescript-types-generator](typescript-types-generator/SKILL.md) | `generateTS` / `graphqlTS`, Delivery SDK, GraphQL transport |
+| [testing](testing/SKILL.md) | Jest, unit vs integration, `.env`, fixtures |
+| [code-review](code-review/SKILL.md) | PR review: API surface, CDA/GraphQL terminology, semver |
+
+There is no separate **framework** skill: HTTP and Delivery/GraphQL details are covered in [typescript-types-generator](typescript-types-generator/SKILL.md).
 
-There is no separate **framework** skill: HTTP/GraphQL details are covered in [contentstack-delivery-cda.mdc](../.cursor/rules/contentstack-delivery-cda.mdc) and the typescript skill.
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).
@@ -5,8 +5,6 @@ description: PR review checklist for @contentstack/types-generator (API docs, co
 
 # Code review skill (`@contentstack/types-generator`)
 
-Expanded checklist aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc).
-
 ## Documentation and API surface
 
 - Public exports from [`src/index.ts`](../../src/index.ts) should stay coherent and documented (JSDoc on exported functions where the package documents behavior).