docs: add project contributor guidance

Author: Hellfrosted

docs/adr/0001-mod-config-provider-compatibility.md

@@ -0,0 +1,3 @@
+# Mod config provider compatibility
+
+BetterModMenu will expose one selected-mod `Config` action while using provider-specific compatibility behind it: direct RitsuLib navigation when available, and a small reflective BaseLib fallback when BaseLib is the only provider for a mod. This avoids crowding the mod UI with provider choices while acknowledging that RitsuLib exposes a direct settings navigator and BaseLib currently exposes registration but not an equivalent public direct-open API.

docs/agents/code-conventions.md

@@ -0,0 +1,21 @@
+# Code Conventions
+
+Last updated: 2026-05-01
+
+## C#
+
+- Keep nullable reference types enabled and respect existing nullability annotations.
+- Prefer concise, simple C# that follows the surrounding file's style.
+- Keep game-facing behavior in patch/session classes and reusable pure logic in `Data/` or rule/helper classes when that pattern already exists.
+- Prefer named constants for shared UI text, group names, and behavioral constants.
+
+## Project Structure
+
+- `Data/`: profile state, manifest scanning, persistence, and portable-mode path logic.
+- `Patches/`: Harmony/Godot mod screen integration and UI operations.
+- `BetterModMenu.Tests/`: MSTest coverage for pure rules and file/path behavior.
+
+## Dependencies
+
+- Do not add dependencies without asking first.
+- Prefer .NET and Godot APIs already available in the project.

docs/agents/commands.md

@@ -0,0 +1,45 @@
+# Commands
+
+Last updated: 2026-05-01
+
+## Validation
+
+Run the smallest command that proves the change:
+
+```bash
+dotnet test BetterModMenu.Tests/BetterModMenu.Tests.csproj
+```
+
+Use the solution-level test command when changes cross project boundaries:
+
+```bash
+dotnet test BetterModMenu.sln
+```
+
+There is no standalone typecheck command for this repository.
+
+## Build
+
+Do not run build commands unless specifically asked. Building the mod requires `sts2.dll`:
+
+```bash
+dotnet build BetterModMenu.csproj -p:Sts2DllPath="C:\path\to\sts2.dll"
+```
+
+If `STS2_DLL_PATH` is already set, the project file uses it automatically.
+
+## Packaging
+
+Do not package unless specifically asked:
+
+```bash
+dotnet build BetterModMenu.csproj -p:Sts2DllPath="C:\path\to\sts2.dll" -p:PackageModOnBuild=true
+```
+
+Packaged archives are written to `artifacts/`.
+
+## Command Preferences
+
+- Do not run dev server commands.
+- Do not run build commands unless specifically asked.
+- Avoid `npm` and `yarn`; they are not used in this repository.

docs/agents/instruction-audit.md

@@ -0,0 +1,42 @@
+# Instruction Audit
+
+Last updated: 2026-05-01
+
+## Contradictions
+
+No hard contradictions were found in the supplied instructions for this repository.
+
+The only scope mismatch is that some global preferences, such as TypeScript and package-manager defaults, do not apply to this C# Godot/.NET project. They were not copied into the project-local guidance except where useful as negative command guidance.
+
+## Essentials Kept In Root
+
+- One-sentence project description.
+- Package manager status.
+- SDK and build constraint.
+- Note that there is no standalone typecheck command.
+- Build command syntax for the non-standard `sts2.dll` requirement.
+- Default validation command.
+- Links to deeper guidance.
+
+## Suggested `docs/` Structure
+
+```text
+docs/
+  agents/
+    workflow.md
+    commands.md
+    code-conventions.md
+    testing.md
+    release-packaging.md
+    instruction-audit.md
+```
+
+## Flagged For Deletion Or Omission
+
+- "Always strive for concise, simple solutions." Too vague to enforce as a project-specific rule.
+- "If a problem can be solved in a simpler way, propose it." Useful preference, but redundant with normal agent behavior and the workflow guidance.
+- TypeScript-specific guidance. Not relevant to this repository unless TypeScript is introduced later.
+- Package-manager preference for pnpm or bun. Not relevant because this repository has no JavaScript package manager.
+- "Use Agent CI only when the repo supports it..." Omitted because this repository has no Agent CI setup in the project files.
+- Broad tech-stack preferences such as Tailwind, React, Convex, Clerk, and Vercel. Not relevant to a C# Godot mod.
+- General reminders like "write clean code" or "prefer existing patterns" were either omitted or converted into repository-specific guidance.

docs/agents/release-packaging.md

@@ -0,0 +1,24 @@
+# Release And Packaging
+
+Last updated: 2026-05-01
+
+## Mod Manifest
+
+- Keep `BetterModMenu.json` aligned with release changes.
+- Preserve the mod id `BetterModMenu` unless explicitly asked to change it.
+- `affects_gameplay` should remain `false` unless the mod starts changing gameplay behavior.
+
+## Packaging
+
+- Packaging is controlled by the `PackageModOnBuild` MSBuild property.
+- Packaging copies `BetterModMenu.dll` and `BetterModMenu.json` into a versioned zip under `artifacts/`.
+- Cloud-capable packaging is controlled separately by `IncludeCloudFeatures=true`; default release artifacts must remain local-only.
+- Cloud-capable archives use the `_cloud` suffix so they remain optional alongside the default artifact.
+- The Nexus upload workflow intentionally selects the default `BetterModMenu_v*.zip` archive and excludes `*_cloud.zip` sidecars.
+- Nexus file descriptions should stay short: an automated upload line, the GitHub release URL, and a `Tested on <game version>` placeholder. Keep the player-facing changelog on the Nexus changelog tab instead.
+- Do not update generated artifacts unless the user asks for a release or packaging task.
+
+## Distribution
+
+- GitHub releases can be mirrored to Nexus Mods through `.github/workflows/publish-nexus-release.yml`.
+- Do not handle credentials, tokens, or session exports in repo files or markdown.

docs/agents/testing.md

@@ -0,0 +1,24 @@
+# Testing
+
+Last updated: 2026-05-01
+
+## Framework
+
+- Tests use MSTest in `BetterModMenu.Tests/`.
+- Prefer focused tests around pure rules, manifest scanning, persistence normalization, and path behavior.
+- Keep tests independent of Slay the Spire 2 and Godot runtime when possible.
+
+## When To Add Tests
+
+- Add or update tests for changes to group/profile rules, manifest parsing, save-data normalization, and path safety.
+- For UI patch changes that are hard to automate, extract pure logic into testable helpers when it is a small, natural fit.
+
+## Verification
+
+Use:
+
+```bash
+dotnet test BetterModMenu.Tests/BetterModMenu.Tests.csproj
+```
+
+If tests cannot run, report the command attempted and the blocking error.

docs/agents/workflow.md

@@ -0,0 +1,30 @@
+# Workflow
+
+Last updated: 2026-05-01
+
+## Scope
+
+- Keep project workflow in the closest `AGENTS.md`.
+- Keep workstation runbooks outside this repo in `C:\Users\nguco\.agents\docs\`.
+- Preserve user changes. Do not revert, overwrite, rename, or reorganize unrelated work unless explicitly asked.
+- Keep changes small, cohesive, aligned with local patterns, and no broader than the task requires.
+
+## Before Editing
+
+- Identify the goal, constraints, done criteria, and verification path before making non-trivial changes.
+- Inspect relevant local guidance plus `README.md`, project files, and task runners when useful.
+- For vague requests, ask one concise clarifying question only when a reasonable default would be risky.
+- When a design is under-specified, surface the key decision, recommend a default, and ask for confirmation before committing to the direction.
+
+## During Work
+
+- Prefer existing helpers, framework APIs, parsers, and conventions before adding new abstractions.
+- Add abstractions only when they remove real duplication or complexity.
+- Clean up temporary artifacts unless they remain useful records.
+- If asked to do too much work at once, stop and say so clearly.
+
+## Git
+
+- Check `git status --short` before non-trivial edits and again before commit or push.
+- Do not include unrelated changes in commits.
+- Do not force-push or run destructive git commands unless explicitly requested.