# AGENTS.md — navigation

Header global for main site navigation. Provides the Header Payload global and tRPC procedures for dynamic navigation content.

## What it owns

- **Entities** — Navigation type (title, links, menu items)
- **Use cases** — Get header, update header
- **Repository interface** — `INavigationRepository` for navigation persistence
- **Mock repository** — In-memory navigation store for tests
- **Payload repository** — Real Payload-backed navigation repository (constructor-injected at boot)
- **Payload global** — Header global definition
- **tRPC router** — Procedures for get header
- **DI container** — Per-feature InversifyJS container with navigation symbols
- **UI components** — Navigation menu, header with branding

## Public exports

From `package.json`:
- `.` — Navigation type + UI components (NavigationMenu, Header)
- `./api` — tRPC router (`navigationRouter`)
- `./cms` — Payload Header global
- `./di/bind-production` — `bindProductionNavigation()` to wire Payload repo at boot

## What it must NOT import

- Any other feature package (`@repo/auth`, `@repo/blog`, etc.)
- Any app package
- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only import from `@repo/core-shared` and use DI for Payload config

## Layer rules

### `src/` files use relative imports

```typescript
// ✓ Correct
import type { INavigationRepository } from "../repositories/navigation.repository.interface.js";

// ✗ Wrong
import { Navigation } from "@/entities/navigation.js";
```

### Tests use @/ alias

```typescript
// ✓ Correct
import { getHeaderUseCase } from "@/application/use-cases/get-header.use-case.js";
```

### DI container is per-feature

Tests rebind:

```typescript
import { container as navContainer, NAV_SYMBOLS } from "@/di/container.js";
import { MockNavigationRepository } from "@/infrastructure/repositories/mock-navigation.repository.js";

beforeEach(() => {
  navContainer.unbindAll();
  navContainer.bind(NAV_SYMBOLS.INavigationRepository).to(MockNavigationRepository);
});
```

## Test conventions

- **Unit tests** colocated: `*.test.ts`
- **Feature tests** in `tests/`: `*.feature.test.ts`
- **Vitest environment** — `node`
- **Alias** — `@/` resolves to `src/`
- **Run** — `pnpm test --filter @repo/navigation`

## Tests

- **Factories:** `src/__factories__/header.factory.ts` and `src/__factories__/nav-item.factory.ts` — use `headerFactory.build({ overrides })` and `navItemFactory.build({ overrides })` to construct test data with stable defaults.
- **Contract suite:** `src/__contracts__/header-repository.contract.ts` — runs against every repository implementation (mock + payload).
- **Unit tests:** colocated as `*.test.ts` next to the source file.
- **Feature integration:** none today (no `tests/` directory yet); add when a multi-layer flow needs end-to-end coverage.

```bash
pnpm test --filter @repo/navigation           # all tests for this feature
pnpm test --filter @repo/navigation -- --watch # watch mode
```

See `docs/guides/tdd-workflow.md` for the cycle.

## Structure (minimal)

Per spec addendum v5 ("create folders only when needed"), this feature is small:

```
src/
  entities/
    navigation.ts            # Navigation/Header schema
  application/
    repositories/
      navigation.repository.interface.ts
    use-cases/
      get-header.use-case.ts
  infrastructure/
    repositories/
      payload-navigation.repository.ts
      mock-navigation.repository.ts
  di/
    symbols.ts
    container.ts
    bind-production.ts
  interface-adapters/
    controllers/
      navigation.controller.ts
  integrations/
    cms/
      globals/
        header.ts            # Payload GlobalConfig
      index.ts
    api/
      router.ts
      index.ts
  ui/
    navigation-menu.tsx
    header.tsx
  index.ts
tests/
  get-header.feature.test.ts
```

No `application/use-cases/` subdirectory; just one or two use-cases at the top level.