diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9b1bd23
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,149 @@
+# AGENTS.md
+
+## Project Overview
+
+This repository contains a standalone Russian localization mod for **Baldur's Gate 3**:
+
+- Mod name: `DnD 5.5e All-in-One BEYOND Russian Localization`
+- Mod folder: `Mods/DnD 5.5e AIO Russian`
+- Base/original mod dependency: `DnD 5.5e All-in-One BEYOND`
+- Original mod repository: `https://github.com/Yoonmoonsik/dnd55e`
+- Original dependency UUID: `897914ef-5c96-053c-44af-0be823f895fe`
+
+This repository is for the localization mod only. It must not gain gameplay logic, Script Extender files, or unrelated assets.
+
+## Repository Rules
+
+- Keep the repository source-only.
+- Do not commit `.pak` artifacts.
+- Do not commit temporary build outputs.
+- Do not add gameplay or script content unrelated to localization/release packaging.
+- Keep the localization folder and metadata consistent with the packaged mod.
+
+## Current Important Paths
+
+- Mod sources: `Mods/DnD 5.5e AIO Russian`
+- Localization XML: `Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml`
+- Mod metadata: `Mods/DnD 5.5e AIO Russian/meta.lsx`
+- CI workflow: `.gitea/workflows/build.yml`
+- Main build script: `scripts/build.ps1`
+
+## Build And Release Model
+
+The authoritative build logic lives in:
+
+- `scripts/build.ps1`
+
+The Gitea workflow should stay thin and only:
+
+1. prepare the workspace
+2. download `Divine`
+3. call `scripts/build.ps1`
+4. publish the release zip for tag builds
+
+### Current Build Outputs
+
+The build script produces:
+
+- `build/DnD 5.5e AIO Russian.pak`
+- `build/info.json`
+- `build/DnD 5.5e AIO Russian <tag>.zip` for tagged builds
+
+The release zip is expected to contain:
+
+- the built `.pak`
+- `info.json`
+
+## Packaging Notes
+
+The package must contain only the BG3 mod structure under `Mods/...`.
+
+Verified expected extracted `.pak` structure:
+
+- `Mods/DnD 5.5e AIO Russian/meta.lsx`
+- `Mods/DnD 5.5e AIO Russian/Localization/Russian/russian.xml`
+
+Do not allow `.git`, `.gitea`, `scripts`, `tools`, `.tools`, `build`, or staging directories into the `.pak`.
+
+## Important Packaging Behavior
+
+There is a runner-specific packaging quirk:
+
+- `Divine` can produce a broken 48-byte `.pak` on the CI runner depending on the source path.
+- Current mitigation is implemented in `scripts/build.ps1`.
+- The script uses staged sources and fallback packaging attempts.
+- Staging is performed in `%TEMP%`, not in a dot-prefixed directory inside the repo.
+
+If packaging breaks again, debug the source path and unpack the resulting `.pak` locally to verify actual contents.
+
+## Versioning
+
+Version displayed by BG3ModManager should be derived from the release tag.
+
+Current behavior:
+
+- `scripts/build.ps1` derives `Version64` from tags like `v0.1.0`
+- the computed version is written into:
+  - generated `info.json`
+  - staged `meta.lsx` before packaging
+
+Do not manually hardcode release versions in the committed `meta.lsx` for each release if CI can derive them from tags.
+
+## info.json Expectations
+
+`info.json` is generated during build and should remain aligned with BG3/BG3ModManager expectations.
+
+Current expected shape:
+
+- top-level `Mods`
+- top-level `MD5`
+- per-mod fields:
+  - `Author`
+  - `Name`
+  - `Folder`
+  - `Version`
+  - `Description`
+  - `UUID`
+  - `Created`
+  - `Dependencies`
+  - `Group`
+
+Current dependency model:
+
+- `Dependencies` is an array of dependency UUIDs
+- current dependency UUID:
+  - `897914ef-5c96-053c-44af-0be823f895fe`
+
+## CI Trigger Policy
+
+Current workflow policy:
+
+- run on tags `v*`
+- run on manual dispatch
+- do not run on every push to `main`
+
+## Git / Collaboration Preferences
+
+User preference:
+
+- after making changes, ask for permission before committing
+- if the user approves, commit and push immediately
+- for significant changes, propose moving work into a separate branch
+- feature/fix branches must use the prefix `feat/` or `fix/`
+- after finishing work in a `feat/` or `fix/` branch, propose merging it back into `main`
+- comments and commit messages should be written in Russian
+
+Do not auto-commit or auto-push without explicit user approval.
+
+## Cleanup Expectations
+
+Temporary directories and debug artifacts should not remain in the repository.
+
+Ignored paths currently include:
+
+- `build/`
+- `build-stage*`
+- `.tools/`
+- `*.pak`
+
+If local debugging creates additional temporary folders, remove them when done unless the user explicitly wants to keep them.