docs(engine): clarify priority so scarce stock favors lower numbers

Document constructor and property semantics and cover priority zero versus nine on one sheet.

Co-Authored-By: Codex <noreply@openai.com>

OpenNest.Engine.Tests/Jobs/StockLadderTests.cs

@@ -5,6 +5,23 @@ namespace OpenNest.Engine.Tests.Jobs;
 
 public class StockLadderTests
 {
+    [Fact]
+    public void LowerPriorityNumberWinsScarceStock()
+    {
+        var geometry = PartGeometrySnapshot.FromProgram(TestDrawingFactory.Rectangle(4, 4));
+        var high = new NestJobPart("high", geometry, 1);
+        var job = new NestJob(
+            new[] { new NestJobPart("low", geometry, 1, priority: 9), high },
+            new[] { new NestPlateStock("only", new Size(4, 4), 1) }
+        );
+
+        var result = new StockLadderNestingEngine().Solve(job);
+
+        Assert.Equal(0, high.Priority);
+        Assert.Equal("high", Assert.Single(Assert.Single(result.Plates).Placements).PartId);
+        Assert.Equal(0, result.Fulfillment.Single(f => f.PartId == "low").Placed);
+    }
+
     private static NestJobPart Rectangle(
         string id,
         int quantity,

OpenNest.Engine/Jobs/NestJobPart.cs

@@ -5,6 +5,13 @@ namespace OpenNest.Engine.Jobs;
 /// <summary>An immutable requirement, independent of drawing names, UI state, and drawing quantity counters.</summary>
 public sealed class NestJobPart
 {
+    /// <summary>Creates an immutable part requirement.</summary>
+    /// <param name="id">Unique requirement ID.</param>
+    /// <param name="geometry">Snapshot of the part geometry.</param>
+    /// <param name="quantity">Positive number requested.</param>
+    /// <param name="priority">Placement precedence: lower numbers are placed first and win scarce
+    /// stock. Zero is the default and highest ordinary priority; equal priorities are peers.</param>
+    /// <param name="rotation">Allowed rotations, or null for automatic rotation.</param>
     public NestJobPart(
         string id,
         PartGeometrySnapshot geometry,
@@ -29,6 +36,10 @@ public sealed class NestJobPart
 
     /// <summary>Positive number requested; never decremented by placement code.</summary>
     public int Quantity { get; }
+    /// <summary>
+    /// Placement precedence: a lower number is placed first and wins scarce stock.
+    /// Zero is the default and highest ordinary priority. Parts with equal priority are peers.
+    /// </summary>
     public int Priority { get; }
     public RotationPolicy Rotation { get; }
 }