Add HLSL SPIR-V tool scripts

.gitignore

@@ -4,3 +4,4 @@ obj/
 **/obj/
 target/
 **/target/
+.tools/

README.md

@@ -72,6 +72,22 @@ cargo test --manifest-path native/cultmath-core/Cargo.toml
 cargo build --release --manifest-path native/cultmath-core/Cargo.toml
 ```
 
+## Shader Tooling
+
+CultMath keeps portable DXC outside git under `.tools/`:
+
+```powershell
+.\tools\get-dxc.ps1
+.\tools\compile-hlsl-spirv.ps1 `
+  -ShaderPath E:\Projects\Odin\crates\muninn-move-tracker\shaders\MoveSphereCandidate.comp.hlsl `
+  -OutputPath E:\Projects\Odin\crates\muninn-move-tracker\artifacts\shader\MoveSphereCandidate.comp.spv `
+  -IncludePath E:\Projects\CultMath\shaders
+```
+
+DXC emits Vulkan SPIR-V with `-spirv`. `-TargetEnv vulkan1.2` is exposed by the
+script, but the current Windows DXC release compiled this shader successfully
+with DXC's default Vulkan target while rejecting the dotted target-env value.
+
 ## Doctrine
 
 The goal is mechanical sympathy between CPU-side authoring, native kernels, and

tools/compile-hlsl-spirv.ps1

@@ -0,0 +1,58 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$ShaderPath,
+
+    [Parameter(Mandatory = $true)]
+    [string]$OutputPath,
+
+    [string]$EntryPoint = "main",
+    [string]$Profile = "cs_6_0",
+    [string[]]$IncludePath = @(),
+    [string]$TargetEnv = "",
+    [string]$DxcPath = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+$repoRoot = Resolve-Path (Join-Path $PSScriptRoot "..")
+if (-not $DxcPath) {
+    $DxcPath = Join-Path $repoRoot ".tools\dxc\current\bin\x64\dxc.exe"
+}
+
+if (-not (Test-Path $DxcPath)) {
+    throw "DXC not found at '$DxcPath'. Run tools\get-dxc.ps1 first or pass -DxcPath."
+}
+
+$resolvedShader = Resolve-Path $ShaderPath
+$resolvedIncludes = @((Join-Path $repoRoot "shaders"))
+foreach ($path in $IncludePath) {
+    $resolvedIncludes += (Resolve-Path $path)
+}
+
+$outputDirectory = Split-Path -Parent $OutputPath
+if ($outputDirectory) {
+    New-Item -ItemType Directory -Force -Path $outputDirectory | Out-Null
+}
+
+$arguments = @(
+    "-T", $Profile,
+    "-E", $EntryPoint,
+    "-spirv"
+)
+
+if ($TargetEnv) {
+    $arguments += "-fspv-target-env=$TargetEnv"
+}
+
+foreach ($include in $resolvedIncludes) {
+    $arguments += @("-I", $include)
+}
+
+$arguments += @($resolvedShader, "-Fo", $OutputPath)
+
+& $DxcPath @arguments
+if ($LASTEXITCODE -ne 0) {
+    throw "dxc.exe failed with exit code $LASTEXITCODE."
+}
+
+Get-Item -LiteralPath $OutputPath

tools/get-dxc.ps1

@@ -0,0 +1,42 @@
+param(
+    [string]$InstallRoot = ".tools\dxc"
+)
+
+$ErrorActionPreference = "Stop"
+
+$repoRoot = Resolve-Path (Join-Path $PSScriptRoot "..")
+$installPath = Join-Path $repoRoot $InstallRoot
+New-Item -ItemType Directory -Force -Path $installPath | Out-Null
+
+$release = Invoke-RestMethod `
+    -Uri "https://api.github.com/repos/microsoft/DirectXShaderCompiler/releases/latest" `
+    -Headers @{ "User-Agent" = "CultMath-DXC-Bootstrap" }
+
+$asset = $release.assets |
+    Where-Object { $_.name -like "dxc_*.zip" } |
+    Select-Object -First 1
+
+if (-not $asset) {
+    throw "No Windows dxc_*.zip asset found on the latest DirectXShaderCompiler release."
+}
+
+$zipPath = Join-Path $installPath $asset.name
+Remove-Item -LiteralPath $zipPath -Force -ErrorAction SilentlyContinue
+
+& curl.exe -L --retry 5 --retry-delay 2 --fail -o $zipPath $asset.browser_download_url
+if ($LASTEXITCODE -ne 0) {
+    throw "curl.exe failed with exit code $LASTEXITCODE."
+}
+
+$currentPath = Join-Path $installPath "current"
+Remove-Item -LiteralPath $currentPath -Recurse -Force -ErrorAction SilentlyContinue
+New-Item -ItemType Directory -Force -Path $currentPath | Out-Null
+Expand-Archive -LiteralPath $zipPath -DestinationPath $currentPath -Force
+
+$dxcPath = Join-Path $currentPath "bin\x64\dxc.exe"
+if (-not (Test-Path $dxcPath)) {
+    throw "DXC x64 executable was not found after extraction."
+}
+
+& $dxcPath --version
+Write-Host "DXC installed at $dxcPath"