📝 Scribe: Add XML documentation for Housing and Gold Saucer agents

.jules/scribe.md

@@ -10,3 +10,4 @@
 ## 2026-06-24 - [RemoteAgents] Learning: "Dawn" is the internal game name for the Duty Support and Trust systems. Action: When documenting "Dawn" related agents or offsets, explicitly reference both Duty Support and Trust to ensure clarity for developers familiar with the in-game terminology.
 ## 2026-06-25 - [AetherialWheel] Learning: FC Aetherial Wheel data includes multiple item IDs (Starting, Current, Resulting) to track the transformation of a wheel as it primes. Action: When documenting aetherial wheel structures, distinguish between the unprimed source item and the final primed result to clarify the priming lifecycle.
 ## 2026-07-20 - [TripleTriadExchange] Learning: Triple Triad cards are exchanged for Manderville Gold Saucer Points (MGP), which are distinct from Grand Company Seals/Coins. Action: Always verify currency types in exchange interfaces to ensure accurate domain terminology.
+## 2026-07-06 - [HousingAgents] Learning: AgentHousingSignBoard has 1-based Ward and Plot numbers derived from raw memory. Action: Explicitly mention 1-based indexing in documentation to avoid off-by-one errors for callers.

Enums/PlotSize.cs

@@ -1,9 +1,15 @@
-namespace LlamaLibrary.Enums
+namespace LlamaLibrary.Enums
 {
+    /// <summary>
+    /// Defines the sizes of housing plots in FFXIV.
+    /// </summary>
     public enum PlotSize : byte
     {
+        /// <summary>A small housing plot (Cottage).</summary>
         Small,
+        /// <summary>A medium housing plot (House).</summary>
         Medium,
+        /// <summary>A large housing plot (Mansion).</summary>
         Large
     }
-}
+}

RemoteAgents/AgentGoldSaucerInfo.cs

@@ -5,13 +5,21 @@
 
 namespace LlamaLibrary.RemoteAgents
 {
+    /// <summary>
+    /// Remote agent for Gold Saucer information.
+    /// Provides access to data and state related to the Manderville Gold Saucer, such as currency and mini-game status.
+    /// </summary>
     public class AgentGoldSaucerInfo : AgentInterface<AgentGoldSaucerInfo>, IAgent
     {
+        /// <inheritdoc/>
         public IntPtr RegisteredVtable => AgentGoldSaucerInfoOffsets.VTable;
 
-
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AgentGoldSaucerInfo"/> class.
+        /// </summary>
+        /// <param name="pointer">The memory address of the agent.</param>
         protected AgentGoldSaucerInfo(IntPtr pointer) : base(pointer)
         {
         }
     }
-}
+}

RemoteAgents/AgentHousing.cs

@@ -5,14 +5,21 @@
 
 namespace LlamaLibrary.RemoteAgents
 {
+    /// <summary>
+    /// Remote agent for the housing system.
+    /// Acts as a base or general agent for housing-related operations and state management.
+    /// </summary>
     public class AgentHousing : AgentInterface<AgentHousing>, IAgent
     {
+        /// <inheritdoc/>
         public IntPtr RegisteredVtable => AgentHousingOffsets.VTable;
 
-
-
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AgentHousing"/> class.
+        /// </summary>
+        /// <param name="pointer">The memory address of the agent.</param>
         protected AgentHousing(IntPtr pointer) : base(pointer)
         {
         }
     }
-}
+}

RemoteAgents/AgentHousingSelectBlock.cs

@@ -6,24 +6,40 @@
 
 namespace LlamaLibrary.RemoteAgents
 {
+    /// <summary>
+    /// Remote agent for the housing ward selection interface.
+    /// Manages the display and selection of residential wards and their plot availability.
+    /// </summary>
     public class AgentHousingSelectBlock : AgentInterface<AgentHousingSelectBlock>, IAgent
     {
+        /// <inheritdoc/>
         public IntPtr RegisteredVtable => AgentHousingSelectBlockOffsets.VTable;
-
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AgentHousingSelectBlock"/> class.
+        /// </summary>
+        /// <param name="pointer">The memory address of the agent.</param>
         protected AgentHousingSelectBlock(IntPtr pointer) : base(pointer)
         {
         }
 
+        /// <summary>
+        /// Gets or sets the zero-based index of the currently selected ward in the selection list.
+        /// </summary>
         public int WardNumber
         {
             get => Core.Memory.Read<int>(Pointer + AgentHousingSelectBlockOffsets.WardNumber);
             set => Core.Memory.Write(Pointer + AgentHousingSelectBlockOffsets.WardNumber, value);
         }
 
+        /// <summary>
+        /// Reads the status of housing plots from game memory for the selected ward.
+        /// </summary>
+        /// <param name="count">The number of plots to read (typically 30 or 60 depending on the ward type).</param>
+        /// <returns>A byte array representing plot availability or status.</returns>
         public byte[] ReadPlots(int count)
         {
             return Core.Memory.ReadArray<byte>(Pointer + AgentHousingSelectBlockOffsets.PlotOffset, count);
         }
     }
-}
+}

RemoteAgents/AgentHousingSignBoard.cs

@@ -7,35 +7,70 @@
 
 namespace LlamaLibrary.RemoteAgents
 {
+    /// <summary>
+    /// Remote agent for the housing signboard interface.
+    /// Manages information displayed when interacting with a housing plot's signboard, including sale status and lottery details.
+    /// </summary>
     public class AgentHousingSignboard : AgentInterface<AgentHousingSignboard>, IAgent
     {
+        /// <inheritdoc/>
         public IntPtr RegisteredVtable => AgentHousingSignBoardOffsets.VTable;
 
-
-
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AgentHousingSignboard"/> class.
+        /// </summary>
+        /// <param name="pointer">The memory address of the agent.</param>
         protected AgentHousingSignboard(IntPtr pointer) : base(pointer)
         {
         }
 
+        /// <summary>
+        /// Gets the TerritoryType ID of the zone where the house is located.
+        /// </summary>
         public ushort Zone => Core.Memory.Read<ushort>(Pointer + AgentHousingSignBoardOffsets.Zone);
 
+        /// <summary>
+        /// Gets the 1-based ward number of the plot.
+        /// </summary>
         public byte Ward => (byte)(Core.Memory.Read<byte>(Pointer + AgentHousingSignBoardOffsets.Ward) + 1);
 
+        /// <summary>
+        /// Gets the 1-based plot number within the ward.
+        /// </summary>
         public byte Plot => (byte)(Core.Memory.Read<byte>(Pointer + AgentHousingSignBoardOffsets.Plot) + 1);
 
+        /// <summary>
+        /// Gets a value indicating whether the plot is currently for sale.
+        /// </summary>
         public bool ForSale => Core.Memory.Read<bool>(Pointer + AgentHousingSignBoardOffsets.ForSale);
 
+        /// <summary>
+        /// Gets the size classification of the plot (Small, Medium, or Large).
+        /// </summary>
         public PlotSize Size => (PlotSize)Core.Memory.Read<byte>(Pointer + AgentHousingSignBoardOffsets.Size);
 
+        /// <summary>
+        /// Gets the winning number for the most recently concluded housing lottery on this plot.
+        /// </summary>
         public ushort WinningLotteryNumber => Core.Memory.Read<ushort>(Pointer + AgentHousingSignBoardOffsets.LotteryEntryCount + 0xC);
 
+        /// <summary>
+        /// Gets the total number of entries submitted for the current or most recent housing lottery.
+        /// </summary>
         public ushort LotteryEntryCount => Core.Memory.Read<ushort>(Pointer + AgentHousingSignBoardOffsets.WinningLotteryNumber);
 
+        /// <summary>
+        /// Gets a value indicating whether the plot is owned by a Free Company.
+        /// </summary>
         public bool FcOwned => Core.Memory.Read<int>(Pointer + AgentHousingSignBoardOffsets.FcOwned) != 0;
 
+        /// <summary>
+        /// Returns a string representation of the housing plot information.
+        /// </summary>
+        /// <returns>A formatted string containing the zone, ward, plot, sale status, size, lottery data, and ownership.</returns>
         public override string ToString()
         {
             return $"Zone: {Zone}, Ward: {Ward}, Plot: {Plot}, ForSale: {ForSale}, Size: {Size}, LotteryEntryCount: {LotteryEntryCount}, WinningLotteryNumber: {WinningLotteryNumber}, FcOwned: {FcOwned}";
         }
     }
-}
+}