chore(repo): organize solution, documentation and repository checks

.editorconfig

@@ -0,0 +1,6 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+insert_final_newline = true

.gitattributes

@@ -1,7 +1,7 @@
 ###############################################################################
 # Set default behavior to automatically normalize line endings.
 ###############################################################################
-* text=auto
+* text=auto eol=lf
 
 ###############################################################################
 # Set default behavior for command prompt diff.

.github/workflows/ci.yml

@@ -19,9 +19,12 @@ jobs:
       - uses: actions/setup-dotnet@v4
         with:
           global-json-file: global.json
+      - name: Verify solution structure
+        shell: pwsh
+        run: ./scripts/Verify-SolutionStructure.ps1
       - name: Restore
-        run: dotnet restore src/ChessRealms.ChessEngine.sln --locked-mode
+        run: dotnet restore ChessRealms.ChessEngine.slnx --locked-mode
       - name: Release build
-        run: dotnet build src/ChessRealms.ChessEngine.sln --configuration Release --no-restore
+        run: dotnet build ChessRealms.ChessEngine.slnx --configuration Release --no-restore
       - name: Fast tests
-        run: dotnet test src/ChessRealms.ChessEngine.sln --configuration Release --no-build --filter "TestCategory!=Deep"
+        run: dotnet test ChessRealms.ChessEngine.slnx --configuration Release --no-build --filter "TestCategory!=Deep"

.gitignore

@@ -360,4 +360,4 @@ MigrationBackup/
 .ionide/
 
 # Fody - auto-generated XML schema
-FodyWeavers.xsd
+FodyWeavers.xsd

AGENTS.md

@@ -0,0 +1,11 @@
+# Repository instructions
+
+- Follow [CONTRIBUTING.md](CONTRIBUTING.md).
+- Keep the physical repository layout and solution structure in sync.
+- Run `pwsh -NoProfile -File scripts/Verify-SolutionStructure.ps1` when changing
+  docs, scripts, the solution, or the set or location of projects.
+- Use LF line endings and respect `.editorconfig` and `.gitattributes`.
+- Run checks appropriate to the changes, following CONTRIBUTING.md.
+- In the final response, include proposed commit and PR titles, check results,
+  and validation limits. Providing titles does not authorize an automatic
+  commit, push, or PR creation.

CONTRIBUTING.md

@@ -0,0 +1,132 @@
+# Contributing
+
+## Prerequisites and checks
+
+Install Git, PowerShell 7 (`pwsh`), and .NET SDK **10.0.401**, the exact stable
+version pinned in `global.json`. Restore needs access to NuGet.org or a cache
+containing the locked packages. No additional PowerShell modules are required.
+
+Run these commands from the repository root:
+
+```sh
+pwsh -NoProfile -File scripts/Verify-SolutionStructure.ps1
+dotnet sln ChessRealms.ChessEngine.slnx list
+dotnet restore ChessRealms.ChessEngine.slnx --locked-mode
+dotnet build ChessRealms.ChessEngine.slnx -c Release --no-restore
+dotnet test ChessRealms.ChessEngine.slnx -c Release --no-build --filter "TestCategory!=Deep"
+git diff --check
+```
+
+For the ordinary developer loop, run `dotnet test` from the root. Run the structure
+check whenever docs, scripts, the solution, or project membership/locations change.
+For code, project, solution, SDK, dependency, or build/CI changes, also run locked
+restore, the Release build, and the fast tests above. Documentation-only changes
+need the structure check, link/command review, and `git diff --check`.
+
+Deep tests and performance runs are opt-in when relevant to the change; see
+[README.md](README.md) for commands. CI checks structure before locked restore,
+Release build, and fast tests on both Windows and Linux. Report local results as
+local results; do not infer a CI, Linux, or Visual Studio pass from them.
+
+## Repository and solution structure
+
+- `ChessRealms.ChessEngine.slnx`: the root solution in XML `.slnx` format.
+- `src/`: six projects (engine, tests, console, perft runner, benchmarks, and
+  magic-number search). Each project stays in its own physical directory.
+- `docs/`: API documentation, support boundaries, and historical validation records.
+- `scripts/`: repository tooling, initially only `Verify-SolutionStructure.ps1`.
+- `.github/workflows/ci.yml`: the Windows/Linux verification workflow.
+- Root files such as `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, `global.json`,
+  and `Directory.Build.props`: repository instructions and shared configuration.
+
+Keep solution folders synchronized whenever files or projects are added, removed,
+renamed, or moved:
+
+- `docs` and `scripts` mirror their physical subdirectories recursively. Add each
+  tracked or new nonignored file once as a Solution Item in the matching folder,
+  using its full path relative to the root solution in a `<File Path="..." />` entry.
+  For example, `<File Path="docs/guides/setup.md" />` belongs in
+  `<Folder Name="/docs/guides/">`. Do not add empty folders
+  or ignored artifacts. Tracked files remain checked even if an ignore rule matches.
+- Put all `.csproj` files under the matching `src` solution structure. A project
+  node represents its own directory, so `src/Example/Example.csproj` belongs directly
+  in `src`, and `src/tools/Example/Example.csproj` belongs in `src/tools`. A project
+  directly in `src` also belongs in `src`. Do not duplicate project source files as
+  Solution Items. Preserve existing project/folder `Id` values, project types,
+  and build configurations. The standard Debug/Release and Any CPU mappings use
+  SLNX defaults, verified against the previous solution during migration.
+- Match spelling and case exactly, including on Windows. Both slash styles in
+  solution paths are supported. SLNX folder elements are direct children of
+  `<Solution>`; their absolute names, such as `/docs/guides/`, define nesting.
+  Ancestor folders may be implicit. Record case-only renames in Git as well.
+
+Keep a single root solution so `dotnet test` can discover it without ambiguity.
+The SDK's `dotnet sln <file.sln> migrate` command converts a classic solution to
+SLNX, but leaves the old file in place. After validating the migration, remove
+the old solution and update current commands. See the
+[official CLI documentation](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-sln).
+
+Run the structure checker after editing the solution. It uses its own location
+to find the repository, works from any current directory, reports discrepancies,
+and exits nonzero on failure. It never fixes files automatically. Keep historical
+reports accurate: preserve commands and results as originally run and add a note
+pointing to current instructions when paths change. Root service files stay at
+the root and do not need entries in `docs`.
+
+## Namespaces and project names
+
+`ChessRealms` is the organization prefix, matching the configured GitHub origin
+`ChessRealms/ChessEngine`. `ChessRealms.ChessEngine` identifies the library;
+suffixes such as `.Tests`, `.Console`, `.Perft`, and `.Benchmark` identify related
+projects by purpose. `ChessRealms.MagicBruteforce` is a supporting tool under the
+same organization. This follows the
+[.NET namespace naming guidance](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/names-of-namespaces).
+
+Keep these names consistent across namespaces, project/assembly names, project
+references, and `InternalsVisibleTo` declarations. Removing the organization prefix
+would change public type names and, if projects are renamed, assembly identities.
+Treat such a rename as an intentional compatibility change with a migration plan.
+There is no technical requirement to rename them when changing solution format.
+
+## Branches, commits, and pull requests
+
+Use `<type>/<short-kebab-case-description>` for branches. Use
+`<type>(<scope>): <short imperative description>` for commit and PR titles; choose
+a concise scope such as `repo`, `engine`, `tests`, or `ci`.
+
+| Branch type | Purpose | Commit / PR prefix |
+| --- | --- | --- |
+| `feature` | Add user-facing functionality | `feat` |
+| `fix` | Correct a defect | `fix` |
+| `docs` | Update documentation | `docs` |
+| `test` | Add or improve tests | `test` |
+| `refactor` | Restructure code without changing behavior | `refactor` |
+| `perf` | Improve performance | `perf` |
+| `ci` | Change continuous integration | `ci` |
+| `chore` | Maintain tooling or repository organization | `chore` |
+
+The branch type is **`feature`**, while the corresponding commit and PR type is
+**`feat`**. All other branch types use the same prefix in commit and PR titles.
+For example:
+
+- `feature/add-uci-support` → `feat(engine): add UCI support`
+- `fix/validate-promotion` → `fix(engine): validate promotion choices`
+- `docs/update-api-guide` → `docs(api): clarify draw claims`
+- `chore/repository-organization` →
+  `chore(repo): organize solution, documentation and repository checks`
+
+Describe the problem, resulting behavior, and scope in the PR. Include relevant
+design choices or compatibility implications, the exact checks run and their
+results (including test counts where available), and any checks not run or other
+validation limits. Link a related issue when one exists. Keep the title and
+description aligned with the final changes reviewers will see.
+
+## Text files
+
+Use UTF-8, LF line endings, and a final newline, following `.editorconfig` and
+`.gitattributes`. Preserve existing indentation unless a change requires otherwise.
+Git automatically classifies text files; do not convert binary files. Add CRLF
+exceptions only when a tool demonstrably requires them. `git add --renormalize`
+normalizes the index but does not rewrite every working-copy file. If normalizing
+existing files, rewrite text files safely and verify that their content is unchanged
+apart from line endings; avoid destructive checkout/reset operations.

ChessRealms.ChessEngine.slnx

@@ -0,0 +1,19 @@
+<Solution>
+  <Folder Name="/docs/" Id="a576d511-a7dd-48da-89d2-a534742656e6">
+    <File Path="docs/dotnet-10-migration.md" />
+    <File Path="docs/game-rules-api.md" />
+    <File Path="docs/game-rules-validation.md" />
+    <File Path="docs/known-issues.md" />
+  </Folder>
+  <Folder Name="/scripts/" Id="9f3eeaa3-c0d2-4d93-af81-f93234779361">
+    <File Path="scripts/Verify-SolutionStructure.ps1" />
+  </Folder>
+  <Folder Name="/src/" Id="7cc56138-8080-42ef-beb6-c075dac09fd8">
+    <Project Path="src/ChessRealms.ChessEngine.Benchmark/ChessRealms.ChessEngine.Benchmark.csproj" Id="029e70a1-269b-4f1f-a132-60011e54392d" Type="9a19103f-16f7-4668-be54-9a1e7a4f7556" />
+    <Project Path="src/ChessRealms.ChessEngine.Console/ChessRealms.ChessEngine.Console.csproj" Id="ced75849-6a1d-4150-879d-103dfcd5c547" Type="fae04ec0-301f-11d3-bf4b-00c04f79efbc" />
+    <Project Path="src/ChessRealms.ChessEngine.Perft/ChessRealms.ChessEngine.Perft.csproj" Id="2c20d484-be51-452b-a393-f8f0c969f72e" Type="9a19103f-16f7-4668-be54-9a1e7a4f7556" />
+    <Project Path="src/ChessRealms.ChessEngine.Tests/ChessRealms.ChessEngine.Tests.csproj" Id="530985ce-2bd3-437a-8c66-c50a98cea318" Type="9a19103f-16f7-4668-be54-9a1e7a4f7556" />
+    <Project Path="src/ChessRealms.ChessEngine/ChessRealms.ChessEngine.csproj" Id="e8906e4a-0ddd-45e8-8c0b-8fbb4b5d832a" Type="9a19103f-16f7-4668-be54-9a1e7a4f7556" />
+    <Project Path="src/ChessRealms.MagicBruteforce/ChessRealms.MagicBruteforce.csproj" Id="5c55e3ca-2541-4ea4-b4b6-3c5aae87fb9d" Type="9a19103f-16f7-4668-be54-9a1e7a4f7556" />
+  </Folder>
+</Solution>

README.md

@@ -8,25 +8,28 @@ dependencies. All six projects target .NET 10.
 Install the stable [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/10.0)
 version **10.0.401**, as pinned in `global.json`. `rollForward: disable` requires
 this exact SDK; `allowPrerelease: false` excludes previews. CI reads the same file.
+Install PowerShell 7 (`pwsh`) and Git for the solution structure check. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for repository layout and contribution rules.
 Run from the repository root:
 
 ```sh
 dotnet --version
-dotnet restore src/ChessRealms.ChessEngine.sln --locked-mode
-dotnet build src/ChessRealms.ChessEngine.sln --configuration Release --no-restore
-dotnet test src/ChessRealms.ChessEngine.sln --configuration Release --no-build --filter "TestCategory!=Deep"
+pwsh -NoProfile -File scripts/Verify-SolutionStructure.ps1
+dotnet restore ChessRealms.ChessEngine.slnx --locked-mode
+dotnet build ChessRealms.ChessEngine.slnx --configuration Release --no-restore
+dotnet test ChessRealms.ChessEngine.slnx --configuration Release --no-build --filter "TestCategory!=Deep"
 ```
 
-For the ordinary developer loop, `cd src` and run `dotnet test`. This builds and
-runs all ordinary tests, including fast perft; no settings file is required.
-The solution lives in `src`, so commands from the repository root need its path.
+For the ordinary developer loop, run `dotnet test` from the repository root.
+This builds and runs all ordinary tests, including fast perft; no settings file is required.
+The solution lives at the repository root; all six projects remain in `src`.
 Tests continue to use NUnit 3 through VSTest, explicitly selected in `global.json`.
 The existing filters and NUnit `Explicit` behavior are unchanged.
 
 Committed `packages.lock.json` files pin direct and transitive package versions
 and content hashes. CI uses `--locked-mode` to reject dependency drift. When
 intentionally updating packages, run
-`dotnet restore src/ChessRealms.ChessEngine.sln --force-evaluate`, review the
+`dotnet restore ChessRealms.ChessEngine.slnx --force-evaluate`, review the
 lock-file changes, and repeat the checks above. When updating the SDK, update
 `global.json` and this README together, then regenerate/review the lock files with
 that SDK. Restore requires access to NuGet.org or a cache containing the locked packages.
@@ -43,21 +46,22 @@ that SDK. Restore requires access to NuGet.org or a cache containing the locked
   opt-in for cost, not failing tests being suppressed. Select them explicitly:
 
 ```sh
-dotnet test src/ChessRealms.ChessEngine.sln --configuration Release --no-build --filter "TestCategory=Deep"
+dotnet test ChessRealms.ChessEngine.slnx --configuration Release --no-build --filter "TestCategory=Deep"
 ```
 
 Run both test commands after the Release build, which compiles all tests. Tests,
 the console perft runner and benchmarks use the same `PerftDriver` implementation.
 
-GitHub Actions (`.github/workflows/ci.yml`) runs restore, Release build and the
-same fast-test command on Windows and Linux with SDK 10.0.401, on pushes and pull requests.
+GitHub Actions (`.github/workflows/ci.yml`) checks solution structure, then runs
+locked restore, Release build and the same fast-test command on Windows and Linux
+with SDK 10.0.401, on pushes and pull requests.
 Deep tests are not part of the default CI job. A local pass does not establish
 that either GitHub Actions job has passed.
 
 Optional coverage check using the existing VSTest collector:
 
 ```sh
-dotnet test src/ChessRealms.ChessEngine.sln -c Release --no-build --filter "TestCategory!=Deep" --collect:"XPlat Code Coverage"
+dotnet test ChessRealms.ChessEngine.slnx -c Release --no-build --filter "TestCategory!=Deep" --collect:"XPlat Code Coverage"
 ```
 
 ### Tool smoke checks

docs/dotnet-10-migration.md

@@ -1,5 +1,10 @@
 # .NET 10 migration
 
+> Repository organization note: the solution now lives at the repository root
+> as `ChessRealms.ChessEngine.slnx`.
+> Commands and results below preserve the paths used at the time of validation.
+> See [CONTRIBUTING.md](../CONTRIBUTING.md) for current commands.
+
 Validated on 2026-09-10, Windows 11 x64. The starting commit was `d8eb1e3`
 (`test: add regression test foundation and .NET 8 CI`), confirmed as `origin/main`
 after fetching. The working tree was clean; no applicable `AGENTS.md` was found.

docs/game-rules-validation.md

@@ -1,5 +1,10 @@
 # Game-rules validation — 2026-09-10
 
+> Repository organization note: the solution now lives at the repository root
+> as `ChessRealms.ChessEngine.slnx`.
+> Commands and results below preserve the paths used at the time of validation.
+> See [CONTRIBUTING.md](../CONTRIBUTING.md) for current commands.
+
 Base: `origin/main` at `49fc3a5` (`.NET 10` migration), containing `d8eb1e3`
 (restored tests and CI). Work branch: `feature/complete-game-rules`.
 No applicable AGENTS.md was present in the repository or ancestor directories.