# AGENTS.md

Guidance for AI coding agents working in this repository.

## Project

Next.js frontend for a Paradox save file parser. It uploads a game save file to a
backend service, polls until parsing finishes, and displays the result in a
grid.

- **Next.js 16** (App Router, Turbopack) with **React 19**
- **TypeScript 6**, **ESLint 9** (flat config), **Prettier 3**
- **ag-grid** for the data grid, **Bootstrap 5** for styling

Source files live in `src/`:

- `app/` for routes,
- `components/` for shared UI
- `services/` for backend calls
- `lib/` for helpers
- `config/` for app config
- `types/` for .d.ts type declaration files

## Terminal

**On Windows, prefer `bash.exe`** — but only a real MSYS2, Cygwin, or
MinGW/Git Bash installation, for example `D:\msys2\usr\bin\bash.exe`.

**Never use `C:\Windows\System32\bash.exe`.** Despite its name it is not a
POSIX bash; it is the launcher stub for WSL. Do not start WSL to run ordinary
commands.

If no MSYS/Cygwin/MinGW bash is installed, **use PowerShell** as the terminal.
PowerShell is the fallback, never WSL.

If bash reports `command not found` for `node` or `npm`, that is a `PATH`
problem rather than a missing install: MSYS2 defaults `MSYS2_PATH_TYPE` to
`minimal`, which discards the Windows `PATH`. Setting it to `inherit` fixes it.

## Commands

```sh
npm run dev      # dev server
npm run build    # production build
npm run lint     # eslint
npm run format   # prettier, rewrites files in src/
npx tsc --noEmit # typecheck
```

### Checking your work

**Always run `npm run lint` and `npm run build` after changing code.** They are
the primary way to find errors in this project, and they catch different
things:

- `npm run lint` reports code errors and style violations. It must finish with
  zero problems — no errors and no warnings.
- `npm run build` catches type errors and build-time problems that lint cannot
  see, such as Node APIs leaking into the edge runtime. It must exit cleanly
  and print no warnings.

`npx tsc --noEmit` is a faster way to check types alone while iterating, but it
does not replace a full build.

Do not report a change as finished until both commands pass.

## Version control

This project is managed with **git**.

**Read-only git commands are fine to use without asking.**
`git status`, `git log`, `git diff`, `git show`, `git blame` and similar inspection commands
may be run freely.

**Never run a git command that changes the repository without the user's
explicit permission.**
This is a strict ban, and it covers everything that writes to the history, the index,
or the working tree including `add`, `commit`, `checkout`, `restore`, `reset`,
`stash`, `branch`, `merge`, `rebase`, `push`, `rm`, etc.

Ask first and wait for a clear yes before running such git command.

## Conventions

Prettier settings live in `.prettierrc` and are not negotiable: **4 spaces, no
semicolons, single quotes, 80 column width**. Run `npm run format` after
editing, or match the surrounding style exactly.

Import from within `src/` using the `@/` alias, for example
`import { getMsgFromError } from '@/lib/errors'`.

Write doc comments as JSDoc (`/** ... */`), which editors show on hover.
Plain `//` and `///` comments do not appear in tooltips.
In `.ts` files put only prose in the JSDoc and let the signature carry the types;
do not duplicate types in `{braces}`.

Catch blocks should not annotate the error. Let it be `unknown` and convert it
with the shared helper:

```ts
} catch (err) {
    const errMsg = getMsgFromError(err)
    ...
}
```

Avoid `any`; `no-explicit-any` is enforced. Prefer `unknown` plus narrowing.

## Things that will bite you

**TypeScript is pinned to 6 on purpose.** Do not upgrade it to 7. The Next.js
ESLint config depends on typescript-eslint, which refuses to run under
TypeScript 7, and that would break `npm run lint` entirely.

**`instrumentation.ts` is compiled for the edge runtime too and it can't be disabled.**
Anything using `fs`, `path`, or other Node APIs must be imported behind the
`process.env.NEXT_RUNTIME === 'nodejs'` guard, or the build warns and pulls
Node-only code into the edge bundle.