# AGENTS.md

Exercise repo: illustrating the transition from DB-backed domain classes
(`DbBase` inheritance) to plain domain objects + DTOs + mappers.

**Working Set (for now): the split projects — `src/Domain`,
`src/Db`, `src/Web`** — focus changes there; leave other
projects untouched unless a yak explicitly says otherwise.

## Rendering diagrams (mermaid → svg)

Mermaid diagrams are rendered to SVG with mermaid-cli (`mmdc`), pinned as a
devDependency in `package.json`. Install it once per clone:

```sh
npm install        # installs @mermaid-js/mermaid-cli into node_modules/
```

Then render with `npx mmdc`, which resolves the local install — the same
command on Linux, macOS and **Windows** (PowerShell/cmd):

```sh
npx mmdc -p puppeteer.config.json -i <diagram>.mmd   # -> <diagram>.mmd.svg
```

`-p puppeteer.config.json` passes the headless-Chrome flags (`--no-sandbox`
et al.) — without it mmdc fails to launch the browser in agent/sandbox
shells. On desktop shells it is not needed: plain `npx mmdc -i <input>`
works. On first run puppeteer downloads its own Chrome. `node_modules/` is
gitignored.

## Running dotnet

dotnet SDK 10 is installed **via mise** (see `mise.toml`). It is NOT on PATH in
agent/sandbox shells, and SDK 10 additionally fails without
`DOTNET_CLI_HOME` in some shells. Always use the wrappers:

```sh
scripts/dotnet.sh build db-subclass-to-dto.sln
scripts/dotnet.sh test db-subclass-to-dto.sln
scripts/run-tests.sh          # full test suite, from repo root
```

The wrappers cd to the repo root (the test runner must run from the parent
directory of the test project), export `DOTNET_CLI_HOME`, and invoke
`mise exec -- dotnet ...`. Do not call bare `dotnet`.

If the first-time-use setup fails with `The file ...
'.dotnet-cli/.dotnet' already exists` or `Operation not permitted` (some
agent/sandbox shells block `$HOME/.dotnet-cli`), point the wrapper at a
repo-local home: `DOTNET_CLI_HOME="$PWD/.dotnet-cli" scripts/dotnet.sh ...`
(add `.dotnet-cli/` to `.gitignore`).

## Yaks (task management with yx)

Tasks are managed with the `yx` CLI; yaks live in git (event store), snapshot
in `.yaks/` (gitignored). Work one yak at a time:

```sh
yx list                        # all yaks and states
yx show "<yak name>"           # full yak context (the task instructions)
yx start "<yak name>"          # set state to wip
yx done "<yak name>"           # set state to done (only after acceptance
                               # criteria pass and changes are committed)
```

- The yak context in `yx show` is the authoritative task description; follow
  its acceptance criteria before `yx done`.
- Children block their parent: do prerequisites (nested under a yak) first.
- Add new tasks: `yx add "<name>"` (nest with `--under "<parent>"`).
- If yx complains `.yaks is not gitignored`, keep `.yaks` in `.gitignore`.

## Conventions

- Target framework: net10.0 (SDK pinned by mise).
- Tests: xUnit, mirroring the src split: `tests/Domain.Tests`,
  `tests/Db.Tests`, `tests/Web.Tests`, with the shared test-data builders in
  `tests/TestData`.
- No EF Core / SQLite / AutoMapper — the DB layer is a small hand-rolled fake
  (pure managed code, cross-platform).
- Commit per yak with a message referencing the yak.