# Agent Guide

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

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 edit `built/`** — this is generated output from `npm run build`. It is gitignored. Always modify source in `src/`.
- **Never hand-edit `test/fixtures/`** — these are Nock HTTP recordings. Re-record with `NOCK_RECORD=1`, not manual edits.
- **`index.d.ts` is manually maintained** — it is the public TypeScript API surface. It must stay in sync with DSL capabilities in `src/lib/migration-steps/`. Changes here affect every TypeScript consumer.
- **CMA version alignment is critical** — this library's `contentful-management` dependency must stay aligned with `contentful-cli`, `contentful-import`, `contentful-export`, and `contentful-batch-libs`. Do not bump it in isolation.
- **This is a library, not a CLI** — the user-facing CLI lives in `contentful-cli`. This repo owns the migration DSL and execution engine. Do not add CLI UX features here; they belong in `contentful-cli`.
- **CommonJS output** — `tsconfig.json` targets CommonJS modules. Do not switch to ESM without coordinating with all downstream consumers.
- **`npm ci` requires `npx allow-scripts` after** — `.npmrc` has `ignore-scripts=true` for security. The `prepare` script will not run automatically; you must explicitly run `npx allow-scripts` for packages that need post-install scripts (like esbuild for vitest).
- **Integration/e2e tests need credentials** — they hit real CMA. Never run them without proper `CONTENTFUL_SPACE_ID`, `CONTENTFUL_INTEGRATION_TEST_CMA_TOKEN`, and `CONTENTFUL_ORGANIZATION_ID` environment variables.
- **Conventional Commits required** — semantic-release derives versions from commit messages. Incorrect commit types will produce wrong version bumps.

## Key Conventions

- **Commit format:** Conventional Commits (enforced by Commitizen, use `npm run cm`)
- **Branch strategy:** `main` (latest) + `beta`/`dev` (prereleases) + feature branches; squash merge
- **Test location:** `test/unit/`, `test/integration/`, `test/end-to-end/` — mirrors `src/` structure
- **Module system:** CommonJS (compiled from TypeScript)
- **Build output:** `built/` directory (must exist before CLI or tests can run)

## Integration Points

**Upstream (this repo consumes):**
- Contentful Management API (CMA) — all content model and entry mutations
- `contentful-management` npm package — SDK for CMA HTTP communication

**Downstream (consumes this repo):**
- `contentful-cli` — wraps this as its `space migration` command
- User migration scripts — consume the library API via `require('contentful-migration')`
- CI pipelines — run migration scripts in automated deployment flows

## Build & Quality

```bash
# Quick verification loop
npm ci && npx allow-scripts && npm run build && npm run test:unit && npm run lint
```