# Agent Guide

<!-- Generated by seed-golden-context | Last updated: 2026-05-07 -->

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](./ARCHITECTURE.md) |
| How to build/test/run | [CONTRIBUTING.md](./CONTRIBUTING.md) |
| Why decisions were made | [docs/ADRs/](./docs/ADRs/) |
| What this repo does | [README.md](./README.md) |
| PR review rules | [.bito/guidelines/](./.bito/guidelines/) |
| Active specs/work | [docs/specs/](./docs/specs/) |

## Sharp Edges & Invariants

- **Never instantiate CMA/CDA clients in this library.** `contentful-management` and `contentful` are devDependencies for type imports only. Consumers provide their own clients.
- **All public exports must go through `lib/index.ts`.** Do not add internal modules to the barrel without confirming downstream consumers need them.
- **`test/` is published to npm** (via `files` field in package.json). Do not put secrets, fixtures with real data, or large binary files in the test directory.
- **`build(deps)` commits trigger patch releases.** Renovate PRs that merge will automatically publish. Be aware that merging a dep bump is equivalent to cutting a release.
- **Breaking changes require `feat!:` or `BREAKING CHANGE` footer.** The `{ breaking: true, release: "major" }` rule in semantic-release maps these to major versions. Missing this causes silent breaking patches (see ADR-002).
- **Do not downgrade `engines.node` below `>=22`.** This was a deliberate v11 breaking change; reverting it would break consumers who upgraded.

## Key Conventions

- **Commit format:** Conventional Commits (enforced by Commitizen config)
- **Branch strategy:** `master` (production) + `beta` (pre-release channel); feature branches merge to `master`
- **Test location:** `test/*.test.js` — tests are plain JS using ts-jest preset
- **Module system:** Node16 (CommonJS output from TypeScript source)
- **TypeScript:** Strict mode, ES2022 target, declarations emitted

## Integration Points

**Upstream (this repo consumes):**
- `contentful-management` — type imports only (`SysLink`, `KeyValueMap`)
- `listr2` — type imports for task wrapper generics

**Downstream (consumes this repo):**
- `contentful-import` — logging, proxy, task wrapping, sequence headers
- `contentful-export` — logging, entity naming utilities
- `contentful-cli` — transitively via import/export

## Build & Quality

```bash
# Quick verification loop
npm ci && npm run build && npm test && npm run lint
```