Agent docs

AGENTS.md

@@ -4,7 +4,7 @@
 
 `SaCommonVS.sln` contains the shared Sarand libraries. `SacsStandardBase` provides core types and utilities; `SacsStandardDbas` provides database support; `SacsStandardProc` provides process and file-processing support; `SacsCoreWeb` provides ASP.NET components; and `SacsStandardAccounts` provides accounting integrations. Mobile support is in `SacsMobileMaui` and `SacsMobileXamarin`. Tests live in `SacsCoreUnitTests` and generally mirror the corresponding source area under `Standard`.
 
-These projects are consumed by sibling repositories, including `..\..\BusinessMgr\Workspace`. Preserve the relative repository layout when validating changes against downstream solutions.
+These projects are consumed by sibling workspaces, including `..\..\BusinessMgr\Workspace`, `..\..\MauiApps\Repositories\Sandtrap\Workspace\Sandtrap`, and `..\..\MauiApps\Repositories\Sandalwood\Workspace`. Preserve the relative layout because downstream solutions use direct project references.
 
 ## Build, Test, and Development Commands
 
@@ -18,13 +18,26 @@ dotnet test SacsCoreUnitTests/SacsCoreUnitTests.csproj --configuration Debug
 
 Use `--configuration Release` for release validation. Build the directly affected project first, then build the solution when a change affects public APIs or shared behavior. Mobile projects may require installed MAUI workloads and platform-specific tooling; report any unavailable workload separately from source failures.
 
+For changes to Common public APIs, target frameworks, packages, or shared behavior, validate the relevant downstream solutions. Coordinate framework upgrades across dependency boundaries. When consumers cannot move atomically, temporarily multi-target shared libraries where practical, migrate consumers, and remove the old target only after no in-scope consumer requires it.
+
 ## Coding Style & Naming Conventions
 
 Match the existing C# conventions: tabs, braces on new lines, top-of-file `using` directives, PascalCase public members, and established `Sacs`, `Sa`, `Sam`, and `Sax` prefixes. Follow nearby code where no repository-wide formatter rule exists. Target the framework versions declared in project files. Do not upgrade frameworks or NuGet packages unless explicitly requested.
 
 Processes derived from `SaProcess_Base` must actively poll `IsInterrupted` during long-running loops and before expensive or blocking stages, then exit promptly when cancellation is requested.
 
-Use Windows CRLF line endings for C# source, Visual Studio project files, configuration files, PowerShell or command scripts, and general documentation. Use LF for web assets and files commonly consumed by Unix tooling, including SVG, HTML, CSS, JavaScript, shell scripts, and YAML. Follow `.gitattributes` as the authoritative policy and preserve the configured ending when editing files.
+Use Windows CRLF line endings for C# source, Visual Studio project files, configuration files, PowerShell or command scripts, and general documentation. Use LF for web assets and files commonly consumed by Unix tooling, including SVG, HTML, CSS, JavaScript, shell scripts, and YAML. Follow `.gitattributes` as the authoritative policy. Whenever a file is created or edited, normalize that file to its required line ending as part of the edit, before validation and handoff; do not defer normalization as a separate cleanup step.
+
+New Markdown documents containing tables must include this document-level style so header and data cells are top aligned:
+
+```html
+<style>
+table th,
+table td {
+	vertical-align: top;
+}
+</style>
+```
 
 ## Testing Guidelines
 
@@ -34,6 +47,8 @@ Tests use MSTest and live in `SacsCoreUnitTests`. Add focused tests under the di
 
 Do not edit generated files or build output under `bin`, `obj`, or `TestResults`. Change source inputs instead. Preserve public API compatibility because multiple sibling solutions consume these libraries. Before implementing a significant architectural or breaking change, describe the affected projects, compatibility implications, and migration approach and wait for agreement.
 
+Treat every affected Git workspace as an independent change set. Check its status before editing, preserve unrelated changes, and report validation separately for each workspace.
+
 ## Conversation Tracking
 
 Read `docs/topics.md` and `docs/component-reviews.md` before starting repository review or follow-up work. Update them when a conversation identifies, starts, completes, or reprioritises work, or when a component is reviewed. Follow the tracking conventions in `docs/README.md` and use ISO `YYYY-MM-DD` dates.

SacsMobileMaui/docs/component-reviews.md

@@ -1,5 +1,12 @@
 # SacsMobileMaui Component Review Register
 
+<style>
+table th,
+table td {
+	vertical-align: top;
+}
+</style>
+
 Last updated: 2026-09-10
 
 | Component | Scope | Status | Date reviewed | Next steps | Notes |

SacsMobileMaui/docs/topics.md

@@ -1,17 +1,37 @@
 # SacsMobileMaui Topic Tracker
 
+<style>
+table th,
+table td {
+	vertical-align: top;
+}
+</style>
+
 Last updated: 2026-09-10
 
 ## Prioritised Topics to Be Actioned
 
 | Priority | Topic | Date noted | Next step | Notes |
 |---|---|---|---|---|
+| P1 | Establish authoritative source control for Sandtrap and Sandalwood | 2026-09-10 | Identify or create the intended repositories/change-tracking location before editing either consumer and confirm how coordinated changes will be reviewed. | No Git repository is currently detected at `MauiApps`, Sandtrap, or Sandalwood. Their applications must change with `SacsMobileMaui`, so untracked consumer edits would make the migration incomplete and difficult to review. |
+| P1 | Repair the MAUI workload and capture the pre-migration mobile baseline | 2026-09-10 | Repair the inconsistent Android workload manifests, select the current SDK explicitly, then restore/build Windows and Android and record Apple-platform validation requirements. | Depends on a usable MAUI toolchain and authoritative consumer source control. The current workload reports a missing `microsoft-net-runtime-android-net9` extension; Apple builds require a compatible Mac/Xcode environment. |
 | P1 | Upgrade `SacsMobileMaui` and its consumers from unsupported .NET MAUI 8/9 to .NET MAUI 10 | 2026-09-10 | Replace MAUI 9 compatibility APIs, align and validate consumer projects, then retarget to `net10.0` and the current MAUI 10 servicing release. | MAUI 9.0.120 is the final MAUI 9 patch, but MAUI 9 support ended on 2026-05-12. Sandalwood and Sandtrap still target MAUI 8 while referencing the `net9.0` shared project. The shared library also uses removed/deprecated compatibility layouts, `Frame`, `MainPage`, and popup APIs. |
 | P1 | Make `SamThreadUtil` and form dialogs genuinely asynchronous and deadlock-safe | 2026-09-10 | Replace synchronous UI-thread bridges with `Task`-returning APIs, update the Sandtrap caller, and add focused tests. | The void `InvokeOnMainThreadSync` overload never waits; the generic overload and `DisplayConfirmSync` block on `Task.Result` and can deadlock on the UI thread. `DisplayAlertSync` also passes an async lambda to `Action`, producing `async void` behavior. |
 | P2 | Correct MAUI native handler type checks | 2026-09-10 | Use `SamEditor` in editor mappings and `SamPicker` in picker mappings; validate each platform-specific option. | Several editor and every picker option currently cast to the wrong custom control type, so configured native styling is silently skipped. |
 | P2 | Fix `SamDatePicker.AllowInvalid` state transition | 2026-09-10 | Change the assignment in the equality guard, verify both transitions, and add tests for display and reset behavior. | Setting `AllowInvalid` to `true` returns before refreshing the control; the guard uses `allowInvalidDate = value`. |
 | P3 | Remove unused resource-stream enumeration | 2026-09-10 | Return `null` immediately after a failed named lookup or implement an intentional lookup strategy that disposes rejected streams. | `GetResourceStream` opens every manifest resource, discards each stream, and returns `null`. |
 
+## .NET 10 Dependencies and Sequence
+
+| Work item | Depends on | Unblocks |
+|---|---|---|
+| Establish Sandtrap and Sandalwood source control | Confirmation of the authoritative repositories or tracking workflow | Safe coordinated edits and review of consumer migration changes |
+| Repair MAUI workloads and capture baseline | Consumer source-control decision; supported current SDK/workloads | Reliable distinction between environment, existing-source, and migration failures |
+| Replace compatibility and obsolete APIs | Baseline evidence | Removal of `Microsoft.Maui.Controls.Compatibility` and clean MAUI 10 compilation |
+| Retarget `SacsMobileMaui`, Sandtrap, and Sandalwood together | Compatibility cleanup; aligned package plan; tracked consumer workspaces | Windows and Android MAUI 10 validation |
+| Validate Apple targets | Retargeted projects; compatible Mac and Xcode | Completion of the cross-platform migration |
+| Address remaining behavioral defects | Stable MAUI 10 baseline; UI-thread defect may move earlier if it blocks testing | Reliable application behavior and focused regression tests |
+
 ## In-Progress Topics
 
 | Priority | Topic | Date noted | Date started | Next step | Notes |

docs/README.md

@@ -2,6 +2,8 @@
 
 This folder records review findings and follow-up work relevant to the Common workspace.
 
+An optional informational overview of sibling workspaces is available in `../../../docs/`. It is outside this Git repository and is not authoritative; this repository's `AGENTS.md` and trackers contain all requirements and owned work.
+
 ## Files
 
 - `topics.md` tracks prioritised work, work in progress, and completed work.

docs/component-reviews.md

@@ -1,5 +1,12 @@
 # Component Review Register
 
+<style>
+table th,
+table td {
+	vertical-align: top;
+}
+</style>
+
 Last updated: 2026-09-10
 
 | Component | Scope | Status | Date reviewed | Next steps | Notes |

docs/topics.md

@@ -1,11 +1,21 @@
 # Topic Tracker
 
+<style>
+table th,
+table td {
+	vertical-align: top;
+}
+</style>
+
 Last updated: 2026-09-10
 
 ## Prioritised Topics to Be Actioned
 
 | Priority | Topic | Date noted | Next step | Notes |
 |---|---|---|---|---|
+| P1 | Capture the pre-migration Common build and test baseline | 2026-09-10 | Build the current non-MAUI projects and run `SacsCoreUnitTests`; record existing warnings, failures, SDK selection, and environmental limitations before changing targets. | Depends on committing the current documentation changes separately so baseline and migration changes remain distinguishable. MAUI baseline work is tracked in the project-specific tracker. |
+| P1 | Prepare Common libraries for the coordinated .NET 10 migration | 2026-09-10 | Repair and pin the .NET 10 toolchain, then temporarily target `net8.0;net10.0` in applicable shared libraries and validate both targets before migrating downstream consumers. | BusinessMgr still targets .NET 8 and consumes Common through direct project references. Remove the temporary .NET 8 targets only after all in-scope consumers have migrated. The separate MAUI migration is tracked under `SacsMobileMaui/docs/topics.md`. |
+| P2 | Decide the disposition of `SacsMobileXamarin` before the .NET 10 migration | 2026-09-10 | Confirm whether to retire it, remove it from the main solution, or plan a separate migration; document the supported consumer path. | The project remains in `SaCommonVS.sln` and references Xamarin.Forms 5. It should not be implicitly included in the normal .NET 10 retargeting. |
 | P1 | Prevent synchronous and asynchronous execution from overlapping in `SaProcess_Base` | 2026-09-09 | Route `RunProcess()` and `RunAsync()` through one guarded start operation and extend the lifecycle tests. | A synchronous call can currently reuse and dispose the asynchronous worker's task data. |
 | P2 | Retain cancellation as a completed process outcome | 2026-09-09 | Store a durable cancellation result until the next process reset and test post-completion state. | `IsInterrupted` currently loses token-based cancellation after task-data cleanup. |
 | P2 | Handle `OperationCanceledException` as cancellation | 2026-09-09 | Catch cancellation separately in `RunProcess()` and avoid recording it as an error. | The general exception handler currently consumes cancellation before `RunAsync()` can distinguish it. |
@@ -16,6 +26,16 @@ Last updated: 2026-09-10
 
 - [`SacsMobileMaui`](../SacsMobileMaui/docs/topics.md) tracks the MAUI framework upgrade, UI-thread helpers, native handlers, controls, and resources.
 
+## .NET 10 Dependencies and Sequence
+
+| Work item | Depends on | Unblocks |
+|---|---|---|
+| Commit documentation and tracking changes | None | A clean pre-migration baseline and focused migration history |
+| Capture Common baseline | Documentation change separation; current SDK availability | Evidence for identifying migration regressions |
+| Decide `SacsMobileXamarin` disposition | Confirmation of whether the legacy project is still consumed | Final Common solution and target-framework scope |
+| Add the .NET 10 SDK pin and temporary Common targets | Common baseline; Xamarin scope decision | BusinessMgr retargeting and non-MAUI .NET 10 validation |
+| Remove temporary .NET 8 Common targets | Completed migration of all in-scope downstream consumers | Final .NET 10-only Common state |
+
 ## In-Progress Topics
 
 | Priority | Topic | Date noted | Date started | Next step | Notes |