Agent Guide

Read this file first. It tells you where to find context in this repo.

Quick Reference

What you need	Where to look
How this repo is structured	ARCHITECTURE.md
How to build/test/run	CONTRIBUTING.md
Why decisions were made	docs/ADRs/
What this repo does	README.md
PR review rules	.bito/guidelines/
Active specs/work	docs/specs/
Version migration guides	MIGRATION.md
Advanced usage patterns	ADVANCED.md
TypeScript usage	TYPESCRIPT.md

Sharp Edges & Invariants

• Always run npm run test:types after modifying types — type regressions are not caught by Vitest unit tests. The tsd type tests in test/types/ are the only gate.
• Always run npm run check after changing build targets — es-check validates that output matches declared ES version targets (ES2017 for CJS/ESM, ES2018 for browser bundles).
• Never modify the axios instance directly — HTTP configuration flows through contentful-sdk-core's createHttpClient. Custom headers go in CreateClientParams.headers.
• Bundle size is CI-enforced — size-limit checks run in CI. If you add a dependency, verify it doesn't blow the 85KB (browser) / 45KB (min) limits via npm run test:size.
• dist/esm-raw/ is an intermediate build artifact — it's Rollup input, not a shipped output. Never import from it or reference it in package.json exports.
• Link resolution happens in contentful-resolve-response — not in this repo. If link resolution is broken, look there.
• Content Source Maps only work with CPA — includeContentSourceMaps: true requires host: 'preview.contentful.com'. It will not work with the CDA.
• __VERSION__ is replaced at Rollup build time — it's defined in rollup.config.js via @rollup/plugin-replace. Don't reference it expecting a value at dev/test time without building first.

Key Conventions

• Commit format: Conventional Commits (enforced by commitizen + husky pre-commit hook)
• Branch strategy: master (production, semantic-release on push) + feature branches, squash merge
• Test location: test/unit/, test/integration/, test/types/
• Module system: Dual ESM + CJS (source is ESM, Rollup produces CJS bundle)
• Import paths: Use .js extensions in TypeScript source imports (ESM convention)
• Source lives in: lib/ (not src/)
• Types live in: lib/types/ (shipped as dist/types/)

Integration Points

Upstream (this repo consumes):

• contentful-sdk-core — HTTP client factory, rate limiting, retry, error normalization
• contentful-resolve-response — link resolution algorithm
• @contentful/content-source-maps — CSM encoding/decoding
• @contentful/rich-text-types — Rich Text type definitions
• Contentful CDA/CPA HTTP APIs

Downstream (consumes this repo):

• Customer JavaScript/TypeScript applications
• Framework integrations (Next.js, Gatsby, Nuxt)
• Contentful Live Preview SDK
• Vercel Content Link

Build & Quality

# Quick verification loop
npm ci && npm run build && npm test && npm run check