# 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

- **Single-file library** — All implementation lives in `index.js`. There is no `src/` directory or multi-file architecture. Do not split into multiple files without an ADR.
- **Input immutability contract** — The library deep-copies input via `fast-copy` before mutation. Never remove or bypass this copy step; consumers rely on their input being unmodified.
- **UNRESOLVED_LINK sentinel** — Uses a unique empty object (`{}`) as a sentinel, not `null`/`undefined`/`Symbol`. Do not change this pattern; it avoids polyfill bloat and is used for identity comparison.
- **ResourceLink provider check** — Only `Contentful:` prefixed resource links are resolved. Unknown providers must be passed through unchanged, never removed.
- **No TypeScript** — Source is plain JavaScript (ES modules via Babel). Do not add TypeScript without consensus.
- **dist/ is generated** — Never edit files in `dist/`. Always run `npm run build` to regenerate.
- **CHANGELOG.md is generated** — Managed by semantic-release. Never edit manually.
- **Conventional Commits required** — Commitlint enforces conventional commit format. Non-conforming commits will be rejected by the pre-commit hook.

## Key Conventions

- **Commit format:** Conventional Commits enforced by `commitlint` + Husky pre-commit hook
- **Branch strategy:** `master` (production) + feature branches; `beta` and `dev` for pre-releases
- **Test location:** `test/unit/` with Mocha + Chai
- **Module system:** Dual CJS + ESM (source is ESM, Babel outputs both)
- **Formatting:** Prettier (120 chars, no semicolons, single quotes)

## Integration Points

**Upstream (this repo consumes):**
- Contentful CDA JSON response shape — the `{ items, includes }` contract

**Downstream (consumes this repo):**
- `contentful.js` — the official Contentful JavaScript SDK depends on this package for link resolution
- Direct npm consumers — developers resolving CDA responses outside the SDK

## Build & Quality

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