created AGENTS.md

AGENTS.md

@@ -0,0 +1,118 @@
+# 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.