# Agent Guide

Also see the other related technical documentation in the docs folder.

## Tools

These tool paths should be used instead of any entry in the PATH environment variable: 

- Python is installed in `C:\Users\frank\AppData\Local\Programs\Python\Python314`.
- MiKTeX portable is installed in `D:\Code\miktex-portable\texmfs\install\miktex\bin\x64`.
- Tesseract is installed in `C:\Program Files\Sejda PDF Desktop\resources\vendor\tesseract-windows-x64`.

## Rules

- After every iteration, run `dotnet jb cleanupcode --build=False '$file1' '$file2' ...` for every C# file you touched.
- After the implementation is finished, verify all changed files, and run `python D:\Code\crlf.py $file1 $file2 ...` only for files you recognize, in order to normalize all line endings of all touched files to CRLF.
- After every frontend change, verify the results using an ephemeral Playwright run.
  - For ad hoc verification in this repo, do not default to `npx playwright test` with a temp spec outside the repo.
  - Prefer a repo-local ephemeral Node script under `artifacts_verify/` that imports `playwright` with `require('playwright')` and drives the browser directly.
  - If using the Playwright test runner, use the repo-local CLI at `node_modules\.bin\playwright.cmd` and keep the spec inside the repo so local `node_modules` resolution works.
  - Do not mix the global Playwright CLI with the repo-local `@playwright/test` package.
  - When browser verification needs the app running, launch the app against a temporary copy of `src\RolemasterDb.App\rolemaster.db` so verification does not mutate the canonical DB.

### PowerShell

- This is a Windows environment, WSL is not installed (i.e. sed is not available). You're running under PowerShell 7.5.5. Due to platform restrictions, file deletions are not possible. Replacing the entire file content via a context diff is a viable alternative.
- PowerShell doesn't support bash-style heredocs. If complex scripts need to be executed, consider using python as a last resort. Run Python code using python -c with inline commands instead of python - <<'PY'.
- Parallel PowerShell calls are flaky, stick to sequential reads and command execution.
- Commands like `rg` and `Get-Content` are always allowed.

### Dotnet CLI

- If a build fails with 0 errors / 0 warnings:
  - Do not keep retrying the same build command
  - Consider using --no-restore.
  - Consider using `$env:DOTNET_SKIP_FIRST_TIME_EXPERIENCE = '1'`
  - Consider using `$env:NUGET_PACKAGES = Join-Path $env:USERPROFILE '.nuget\packages'`
- If you need a separate output directory, use a subfolder under `artifacts`, and clean it up afterwards.
- Avoid running `dotnet build` and `dotnet test` in parallel in this repo; that can cause file-lock failures in `obj\Debug\net10.0`.
