📝 Scribe: Add XML documentation for Housing and Inclusion Shop Agents

.jules/scribe.md

@@ -9,3 +9,4 @@
 ## 2026-07-15 - [ProductPatterns] Learning: Multi-region memory support is implemented via a central registry that maps regional identifiers (Global, China, Korea) to product-specific pattern dictionaries. Action: When documenting pattern-related types, clarify that these strings are raw signatures used by the assembly loader to resolve memory offsets across different game versions.
 ## 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 - [AgentHousing] Learning: Housing ward and plot numbers are stored as 0-based values in memory but are presented as 1-based values in the game UI and library properties. Action: Always clarify the 1-based vs 0-based nature of housing indices in documentation to prevent off-by-one errors in profile logic.

RemoteAgents/AgentHousing.cs

@@ -5,12 +5,18 @@
 
 namespace LlamaLibrary.RemoteAgents
 {
+    /// <summary>
+    /// Remote agent for general housing system interactions.
+    /// </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,21 +6,36 @@
 
 namespace LlamaLibrary.RemoteAgents
 {
+    /// <summary>
+    /// Remote agent for the housing ward selection interface.
+    /// </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 housing block.
+        /// </summary>
         public int WardNumber
         {
             get => Core.Memory.Read<int>(Pointer + AgentHousingSelectBlockOffsets.WardNumber);
             set => Core.Memory.Write(Pointer + AgentHousingSelectBlockOffsets.WardNumber, value);
         }
 
+        /// <summary>
+        /// Reads an array of bytes representing the status (e.g., availability) of plots in the selected ward.
+        /// </summary>
+        /// <param name="count">The number of plots to read (usually the total count for the district).</param>
+        /// <returns>A byte array where each element corresponds to a plot's status.</returns>
         public byte[] ReadPlots(int count)
         {
             return Core.Memory.ReadArray<byte>(Pointer + AgentHousingSelectBlockOffsets.PlotOffset, count);

RemoteAgents/AgentHousingSignBoard.cs

@@ -7,32 +7,63 @@
 
 namespace LlamaLibrary.RemoteAgents
 {
+    /// <summary>
+    /// Remote agent for the house or plot signboard interface.
+    /// </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 territory ID of the housing zone.
+        /// </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 of the plot.
+        /// </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 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 recent lottery cycle for this plot.
+        /// </summary>
         public ushort WinningLotteryNumber => Core.Memory.Read<ushort>(Pointer + AgentHousingSignBoardOffsets.LotteryEntryCount + 0xC);
 
+        /// <summary>
+        /// Gets the total number of entries in the current or most recent lottery cycle.
+        /// </summary>
         public ushort LotteryEntryCount => Core.Memory.Read<ushort>(Pointer + AgentHousingSignBoardOffsets.WinningLotteryNumber);
 
+        /// <summary>
+        /// Gets a value indicating whether the plot is currently owned by a Free Company.
+        /// </summary>
         public bool FcOwned => Core.Memory.Read<int>(Pointer + AgentHousingSignBoardOffsets.FcOwned) != 0;
 
+        /// <inheritdoc/>
         public override string ToString()
         {
             return $"Zone: {Zone}, Ward: {Ward}, Plot: {Plot}, ForSale: {ForSale}, Size: {Size}, LotteryEntryCount: {LotteryEntryCount}, WinningLotteryNumber: {WinningLotteryNumber}, FcOwned: {FcOwned}";

RemoteAgents/AgentInclusionShop.cs

@@ -59,16 +59,19 @@ public class AgentInclusionShop : AgentInterface<AgentInclusionShop>, IAgent
 
         /// <summary>
         /// Gets the actual (true) category identifier based on the user's selection index.
+        /// This identifier is used as an index into the shop's structural arrays.
         /// </summary>
         public int TrueCategory => Core.Memory.Read<byte>(StartOfShopThing + AgentInclusionShopOffsets.CategoryArray + SelectedCategory);
 
         /// <summary>
         /// Gets the pointer to the currently active category data.
+        /// This pointer represents the start of the sub-category array for the selected category.
         /// </summary>
         public IntPtr CategoryPtr => Core.Memory.Read<IntPtr>(StartOfShopThing + (TrueCategory * AgentInclusionShopOffsets.StructSizeCategory) + AgentInclusionShopOffsets.SubCategoryArrayStart);
 
         /// <summary>
         /// Gets the base pointer for the currently active category's structure.
+        /// This structure contains metadata about the category, including sub-category counts.
         /// </summary>
         public IntPtr CategoryPtrPtr => StartOfShopThing + (TrueCategory * AgentInclusionShopOffsets.StructSizeCategory);