Sync documentation pack 3.2.3

.agents/conventions/csharp.md

@@ -0,0 +1,68 @@
+# C# / .NET Conventions
+
+**Document role**: Managed coding-agent reference
+**Sync destination**: `.agents/conventions/csharp.md`
+**Local editing**: Do not customize this synced copy
+
+Repository rules, `.editorconfig`, and nearby code take precedence. Do not restyle unrelated files.
+
+## Core Style
+
+| Area | Default when no local rule exists |
+|---|---|
+| Usings | Outside the namespace; `System` first; alphabetized; no blank groups |
+| Namespace | File-scoped |
+| Indentation | Preserve local style; tabs of width 4 for new C# files |
+| Public members and types | `PascalCase` |
+| Private fields | `_camelCase` |
+| Parameters and locals | `camelCase` |
+| Interfaces | `I` prefix |
+| Async methods | `Async` suffix |
+| Constants | `PascalCase` |
+
+Prefer stable, readable code over adopting newer syntax for its own sake.
+
+## Naming and Organization
+
+- Use meaningful names; avoid Hungarian notation and unclear abbreviations.
+- Prefix boolean properties with `Is`, `Has`, `Can`, or `Should` when natural.
+- Use the project convention of an `Enum` suffix for enum types.
+- Reserve enum value `0` for `Unknown`, `Unspecified`, or `None`; real values start at `1`.
+- Order members: constants, fields, properties, events, constructor, expression-bodied members, public methods, protected methods, event raisers, private methods.
+- Prefer `readonly` fields and properties over public mutable fields.
+
+## Control Flow
+
+Single-statement guards may omit braces, but the action must be on the next line. Multi-statement blocks use braces. Follow stricter local rules when present.
+
+```csharp
+if (order == null)
+	throw new ArgumentNullException(nameof(order));
+
+if (!order.IsReady)
+	return;
+```
+
+Never put `return`, `throw`, `break`, or `continue` on the same line as the condition. Add a blank line after a completed control block before the next independent statement; do not separate `else`, `catch`, or `finally` from its preceding brace.
+
+## Modern C#
+
+- Use `var` when the type is obvious; use explicit types when they aid reading.
+- Prefer records for immutable value-like models.
+- Use pattern matching, collection expressions, required members, and primary constructors only when supported and clearer.
+- Avoid `#region` in normal application code.
+- Do not introduce nullable-reference or language-version migrations incidentally.
+
+## Errors, Logging, and Text
+
+- Validate public inputs where invalid values would otherwise fail unclearly.
+- Throw specific exceptions and preserve stack traces with `throw;`.
+- Do not swallow exceptions.
+- Use structured logging placeholders rather than interpolation.
+- Preserve existing punctuation, Unicode, terminal separators, and UI wording style.
+
+## Comments and Tests
+
+- Comment intent, constraints, tradeoffs, and non-obvious behavior—not obvious code.
+- Add focused tests for changed behavior, validation, mappings, parsing, and edge cases.
+- Keep tests deterministic and report flaky or unavailable tests rather than hiding them.

.agents/conventions/python.md

@@ -0,0 +1,28 @@
+# Python Script Conventions
+
+**Document role**: Managed coding-agent reference
+**Sync destination**: `.agents/conventions/python.md`
+**Local editing**: Do not customize this synced copy
+
+Apply repository-specific rules first and use this with `.agents/conventions/scripts.md`.
+
+## Style and Structure
+
+- Preserve existing formatting; use four spaces for new files when no local rule exists.
+- Keep imports at the top and prefer the standard library before adding dependencies.
+- Use small functions, `argparse` for non-trivial CLIs, and `pathlib` for filesystem paths.
+- Keep side effects out of import time.
+- Return an exit code from `main()` and call it with `raise SystemExit(main())`.
+- Use explicit text encodings and readable type hints where useful.
+
+## Reliability
+
+- Validate paths and inputs before writing.
+- Raise or report specific errors; avoid broad exception handling that hides failures.
+- Avoid mutable default arguments.
+- Do not silently overwrite files unless the documented interface explicitly permits it.
+- Keep comments and docstrings for public contracts, constraints, and non-obvious behavior.
+
+## Validation
+
+When applicable, test pure transformations, invalid input, filesystem boundaries, dry-run behavior, generated output, and exit codes. Use the repository's existing test framework.

.agents/conventions/scripts.md

@@ -0,0 +1,35 @@
+# Script Conventions
+
+**Document role**: Managed coding-agent reference
+**Sync destination**: `.agents/conventions/scripts.md`
+**Local editing**: Do not customize this synced copy
+
+Apply repository-specific rules first. Use this file with the applicable language convention.
+
+## Design
+
+- Preserve the existing indentation and output style.
+- Use stable descriptive filenames for version-controlled scripts.
+- Prefer explicit arguments over machine-specific paths.
+- Provide concise `--help` text for non-trivial command-line interfaces.
+- Keep logic in small functions and side effects in the executable path.
+- Print useful errors and return a non-zero exit status on failure.
+
+## Safety
+
+- Validate inputs before expensive or destructive work.
+- Support dry-run mode for bulk copy, move, rename, delete, upload, or rewrite operations.
+- Do not embed secrets or make hidden network calls.
+- Do not overwrite user files silently unless overwrite behavior is explicit and documented.
+- Do not commit, push, open pull requests, or merge unless the task explicitly requires it.
+
+## Files and Output
+
+- Use predictable output names and explicit output locations.
+- Preserve the surrounding ASCII or Unicode presentation style; do not add decoration gratuitously.
+- Avoid creating versioned copies of scripts that Git already tracks.
+- Version distributed artifacts only when the project release process requires it.
+
+## Validation
+
+Run `--help`, representative safe inputs, dry-run mode, and invalid-input cases when applicable. Verify exit codes and generated files.

.agents/conventions/shell.md

@@ -0,0 +1,21 @@
+# Shell Script Conventions
+
+**Document role**: Managed coding-agent reference
+**Sync destination**: `.agents/conventions/shell.md`
+**Local editing**: Do not customize this synced copy
+
+Apply repository-specific rules first and use this with `.agents/conventions/scripts.md`.
+
+## Style and Safety
+
+- Preserve local indentation and shell choice.
+- Prefer POSIX `sh` for simple portable scripts; use Bash when its features improve safety.
+- For compatible Bash scripts, use `set -euo pipefail`.
+- Quote variables unless splitting is intentional.
+- Validate commands, arguments, and paths before bulk or destructive operations.
+- Print errors to stderr and return non-zero on failure.
+- Keep help text and comments concise.
+
+## Validation
+
+Run `--help`, dry-run mode, invalid-input cases, and representative safe inputs when applicable. Run ShellCheck when the repository uses it or it is readily available.

.agents/conventions/unity.md

@@ -0,0 +1,46 @@
+# Unity / C# Conventions
+
+**Document role**: Managed coding-agent reference
+**Sync destination**: `.agents/conventions/unity.md`
+**Local editing**: Do not customize this synced copy
+
+Apply this with `.agents/conventions/csharp.md`. Repository rules and nearby code take precedence.
+
+## Components and Lifecycle
+
+- Keep one `MonoBehaviour` per matching filename.
+- Use plain C# classes for logic that does not need Unity lifecycle or serialization.
+- Prefer `[SerializeField] private` over public inspector fields.
+- Order used callbacks: `Awake`, `OnEnable`, `Start`, `Update`, `LateUpdate`, `FixedUpdate`, `OnDisable`, `OnDestroy`.
+- Cache component references in `Awake`; do not call `GetComponent`, `FindObjectOfType`, or `GameObject.Find` every frame.
+- Subscribe in `OnEnable` and unsubscribe in `OnDisable`.
+- Do not add empty lifecycle methods.
+
+## Unity Objects and Coroutines
+
+- Respect Unity's overloaded lifetime checks for `UnityEngine.Object`; do not use `is null` for Unity objects.
+- In hot paths, use the implicit Unity object check when it is clear.
+- Give coroutine methods a `Coroutine` suffix.
+- Keep a `Coroutine` handle when early cancellation is required.
+- Use explicit state machines for complex interruptible flows.
+
+## Physics and Performance
+
+- Perform physics work in `FixedUpdate`.
+- Move rigid bodies through `Rigidbody` APIs rather than transforms.
+- Avoid repeated allocations, LINQ, string construction, and component lookup in frame callbacks.
+- Pool frequently created gameplay objects where profiling justifies it.
+- Profile before making speculative optimizations.
+
+## Project Structure
+
+- Prefer C# events or `UnityEvent` over `SendMessage`.
+- Use `ScriptableObject` for shared configuration, not mutable runtime state.
+- Keep editor-only code under `Editor/` or guard it with `#if UNITY_EDITOR`.
+- Do not reference `UnityEditor` from runtime assemblies.
+- Centralize tags and layers; use `CompareTag` rather than direct tag-string equality.
+- Follow existing asset naming and rename referenced assets through the Unity Editor.
+
+## Testing
+
+Use Edit Mode tests for pure logic and Play Mode tests for lifecycle, scenes, and runtime integration. Keep Unity-dependent behavior out of plain classes when practical so it remains easy to test.

.agents/guidelines/ci-cd.md

@@ -0,0 +1,26 @@
+# CI/CD Guidance
+
+**Document role**: Managed coding-agent guidance
+**Sync destination**: `.agents/guidelines/ci-cd.md`
+
+Use this guidance for workflows, releases, deployments, or infrastructure automation.
+
+## Boundaries
+
+- Change CI/CD only when the task explicitly requires it.
+- Preserve the provider, triggers, permissions, gates, environments, and secret references.
+- Make the narrowest relevant workflow or job change.
+- Do not add publishing, deployment, infrastructure, or broad write permissions implicitly.
+- Never print secrets or guess secret names.
+- Do not weaken required checks or approvals.
+
+For a new small project, start with checkout, dependency restore, build, tests, and configured lint or format checks. Add publishing or deployment only when its target, trigger, credentials, rollback, and validation are documented.
+
+## Validation
+
+- Check workflow syntax when possible.
+- Run equivalent local commands when practical.
+- Recheck triggers, paths, permissions, environments, and branch targets.
+- State which behavior still requires hosted verification.
+
+Update project documentation when a change affects build commands, releases, deployment, secrets, environments, or approval steps.

.agents/guidelines/documentation.md

@@ -0,0 +1,36 @@
+# Documentation Guidance
+
+**Document role**: Managed coding-agent guidance
+**Sync destination**: `.agents/guidelines/documentation.md`
+
+## Authority
+
+- `README.md` and `CHANGELOG.md` are project-owned entry points.
+- `docs/project/` contains authoritative live documentation.
+- `docs/templates/` contains managed reference templates, not requirements.
+- Never edit target templates or copy placeholders and unverified claims into live documents.
+
+## Update the Relevant Document
+
+- setup, commands, configuration, or public usage: `README.md`
+- meaningful changes: `CHANGELOG.md`
+- capability status and links: `docs/project/features.md`
+- stable components, boundaries, integrations, or data flow: `docs/project/architecture.md`
+- visible workflows and troubleshooting: `docs/project/user-guide.md`
+- functional, technical, or gameplay requirements: the applicable FSD, TSD, or GDD
+
+Update only documents affected by verified behavior. Do not create documentation as busywork.
+
+## Template Review
+
+Scaffolded Markdown contains a source-path marker. It does not track a hash or authorize automatic updates.
+
+When a managed template changes, compare it manually with the live document, using Git history when useful. Apply only relevant structural improvements and preserve verified project content. Sync never rewrites live project documentation.
+
+## Style
+
+- Be concise, factual, and example-driven.
+- Link to detailed documents instead of duplicating them.
+- Curate changelogs; do not paste commit history.
+- Omit unknown information rather than inventing it.
+- Preserve the repository's established formatting and punctuation.

.agents/guidelines/git.md

@@ -0,0 +1,29 @@
+# Git and Pull Request Guidance
+
+**Document role**: Managed coding-agent guidance
+**Sync destination**: `.agents/guidelines/git.md`
+
+Follow repository-specific instructions and hosted settings first.
+
+## Before Starting
+
+When tooling is available:
+
+- inspect the current branch and working tree;
+- fetch and prune remotes;
+- check relevant branches and open or recently merged pull requests.
+
+Do not duplicate existing work or create a missing long-lived branch implicitly.
+
+## Branches, Commits, and Pull Requests
+
+- Use the repository's branching and naming conventions.
+- Otherwise branch from the hosted default branch with a short lowercase kebab-case name.
+- Keep commits focused and imperative.
+- Keep PR titles and descriptions concise and use the repository template.
+- Never force-push a long-lived branch, bypass protection, auto-merge, or approve your own PR.
+- Do not include assistant, model, or tool names in repository history or release text.
+
+Squash short-lived feature branches when desired. When a repository uses long-lived integration and production branches such as `develop` and `main`, preserve merge commits across that boundary for releases, hotfixes, and merge-backs so both branches retain shared ancestry.
+
+If hosted tooling is unavailable, report the intended source branch, target, title, and validation without claiming a PR exists.

.agents/project.md

@@ -0,0 +1,46 @@
+# T5B1 Project Instructions
+
+## Project
+
+T5B1 is a C# .NET game trainer mod for Software Inc. (Beta 1).
+
+- Solution: `Trainer v5 - Beta 1.sln`
+- Source project: `Trainer_v5/Trainer_v5.csproj`
+- Source code: `Trainer_v5/Trainer.Source/`
+- Libraries: `Trainer_v5/Trainer.Libraries/`
+- Localization: `Trainer_v5/Trainer.Localization/`
+
+Preserve the existing architecture, public APIs, project boundaries, naming, tabs in C# files, and user-facing text style.
+
+## Validation
+
+Run the narrowest relevant checks before finishing:
+
+```bash
+dotnet format --verify-no-changes
+dotnet build "Trainer v5 - Beta 1.sln"
+dotnet test "Trainer v5 - Beta 1.sln"
+```
+
+Verify that test projects exist before treating a successful `dotnet test` command as test coverage. Report environment-blocked checks separately from code failures.
+
+## Project Documentation
+
+- Update `README.md` for setup, build, run, or usage changes.
+- Update `CHANGELOG.md` for user-facing additions, changes, fixes, or removals.
+- Update `FEATURES.md` when feature availability or status changes.
+- Do not invent features, compatibility claims, or performance results.
+
+## Git Flow
+
+This repository uses strict Git Flow:
+
+| Branch family | Base | Pull request target | Purpose |
+|---|---|---|---|
+| `feature/*` | `develop` | `develop` | Normal implementation, documentation, tests, maintenance, and non-emergency fixes |
+| `release/*` | `develop` | `main` | Release preparation and stabilization |
+| `hotfix/*` | `main` | `main` | Urgent production fixes |
+
+Do not create other task-branch families. Release and hotfix changes must be brought back to `develop` after merging. Every task branch must create or propose a pull request; never auto-merge or approve your own pull request.
+
+Before branch or pull-request work, fetch and prune remotes, inspect the working tree and current branch, and check existing branches and pull requests to avoid duplicate work.