[LOADED_DOCS: 4 files, no new loads]

Refactor docs: topic folders, TOON, XCUT, protocol sync

- Migrated all topic documentation into dedicated folders with canonical `README.md`, `ISSUES.md`, and `TODO.md` per topic (e.g., `LOGGING/`, `SIGNALR/`, `BINARY/`, `TOON/`).
- Added comprehensive TOON serializer documentation: design, format, options, attributes, inference, issues, and TODOs.
- Introduced `XCUT` folder for cross-cutting issues and TODOs, with canonical entries and topic cross-references.
- Updated all references and navigation to use new folder-based doc paths; fixed links and clarified doc structure.
- Enhanced AI agent protocol: enforce session skill preloading, `[LOADED_DOCS: ...]` short-name prefix, and mandatory `docs-check` skill for doc/code sync.
- Updated `.csproj` to include all `README.md` files for IDE visibility.
- Improved and clarified SignalR, grid, and project-level documentation.
- Minor code/test tweaks and doc content corrections for consistency.

AyCode.Blazor.Components/AyCode.Blazor.Components.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Razor">
+<Project Sdk="Microsoft.NET.Sdk.Razor">
 
 	<PropertyGroup>
 		<RunAOTCompilation>true</RunAOTCompilation>
@@ -57,6 +57,7 @@
 
 	<ItemGroup>
 		<None Include="docs\**\*.md" />
+		<None Include="**\README.md" Exclude="$(DefaultItemExcludes);docs\**" />
 	</ItemGroup>
 
 	<ItemGroup>

AyCode.Blazor.Components/Components/Grids/README.md

@@ -1,6 +1,6 @@
 # Grids
 
-Core grid system built on DevExpress `DxGrid`. For the full technical reference see `AyCode.Blazor.Components/docs/MGGRID.md`.
+Core grid system built on DevExpress `DxGrid`. For the full technical reference see `AyCode.Blazor.Components/docs/MGGRID/README.md`.
 
 ## Key Files
 

AyCode.Blazor.Components/README.md

@@ -13,16 +13,16 @@ Blazor Razor component library targeting .NET 10. Provides reusable DevExpress-b
 
 | Document | Topic |
 |---|---|
-| `MGGRID.md` | MgGrid system — overview, hierarchy, generic params, IMgGridBase interface |
-| `MGGRID_PARAMETERS.md` | Component parameters, event callbacks, default grid settings |
-| `MGGRID_CRUD.md` | Lifecycle, CRUD operations, edit flow, disposal |
-| `MGGRID_LAYOUT.md` | Layout persistence (storage keys, tiers, operations) |
-| `MGGRID_DETAIL.md` | Master-detail hierarchy |
-| `MGGRID_RENDERING.md` | Fullscreen mode, rendering |
-| `MGGRID_INFOPANEL.md` | MgGridInfoPanel, MgGridWithInfoPanel wrapper |
-| `MGGRID_TOOLBAR.md` | MgGridToolbarTemplate (buttons, parameters, state) |
-| `MGGRID_COLUMNS.md` | MgGridDataColumn (InfoPanel params, UrlLink) |
-| `MGGRID_DATASOURCE.md` | MgGridSignalRDataSource (server-side data, local cache) |
+| `MGGRID/README.md` | MgGrid system — overview, hierarchy, generic params, IMgGridBase interface |
+| `MGGRID/MGGRID_PARAMETERS.md` | Component parameters, event callbacks, default grid settings |
+| `MGGRID/MGGRID_CRUD.md` | Lifecycle, CRUD operations, edit flow, disposal |
+| `MGGRID/MGGRID_LAYOUT.md` | Layout persistence (storage keys, tiers, operations) |
+| `MGGRID/MGGRID_DETAIL.md` | Master-detail hierarchy |
+| `MGGRID/MGGRID_RENDERING.md` | Fullscreen mode, rendering |
+| `MGGRID/MGGRID_INFOPANEL.md` | MgGridInfoPanel, MgGridWithInfoPanel wrapper |
+| `MGGRID/MGGRID_TOOLBAR.md` | MgGridToolbarTemplate (buttons, parameters, state) |
+| `MGGRID/MGGRID_COLUMNS.md` | MgGridDataColumn (InfoPanel params, UrlLink) |
+| `MGGRID/MGGRID_DATASOURCE.md` | MgGridSignalRDataSource (server-side data, local cache) |
 
 ## Dependencies
 

AyCode.Blazor.Components/docs/MGGRID/MGGRID_COLUMNS.md

@@ -1,6 +1,6 @@
 # MgGrid — Columns
 
-> Part of the MgGrid system. See `MGGRID.md` for overview and component hierarchy.
+> Part of the MgGrid system. See `README.md` for overview and component hierarchy.
 
 ## MgGridDataColumn
 

AyCode.Blazor.Components/docs/MGGRID/MGGRID_CRUD.md

@@ -1,6 +1,6 @@
 # MgGrid — Lifecycle & CRUD
 
-> Part of the MgGrid system. See `MGGRID.md` for overview and component hierarchy.
+> Part of the MgGrid system. See `README.md` for overview and component hierarchy.
 
 ## Lifecycle
 

AyCode.Blazor.Components/docs/MGGRID/MGGRID_DATASOURCE.md

@@ -1,7 +1,7 @@
 # MgGrid — DataSource
 
-> Part of the MgGrid system. See `MGGRID.md` for overview and component hierarchy.
-> For the underlying `AcSignalRDataSource`: `AyCode.Services.Server/docs/SIGNALR_DATASOURCE.md` (in AyCode.Core repo)
+> Part of the MgGrid system. See `README.md` for overview and component hierarchy.
+> For the underlying `AcSignalRDataSource`: `AyCode.Services.Server/docs/SIGNALR/SIGNALR_DATASOURCE.md` (in AyCode.Core repo)
 
 ## MgGridSignalRDataSource
 

AyCode.Blazor.Components/docs/MGGRID/MGGRID_DETAIL.md

@@ -1,6 +1,6 @@
 # MgGrid — Master-Detail
 
-> Part of the MgGrid system. See `MGGRID.md` for overview and component hierarchy.
+> Part of the MgGrid system. See `README.md` for overview and component hierarchy.
 
 ## How It Works
 

AyCode.Blazor.Components/docs/MGGRID/MGGRID_INFOPANEL.md

@@ -1,6 +1,6 @@
 # MgGrid — InfoPanel
 
-> Part of the MgGrid system. See `MGGRID.md` for overview and component hierarchy.
+> Part of the MgGrid system. See `README.md` for overview and component hierarchy.
 
 ## MgGridWithInfoPanel Wrapper
 

AyCode.Blazor.Components/docs/MGGRID/MGGRID_ISSUES.md

@@ -0,0 +1,27 @@
+# MGGRID — Known Issues
+
+For planned/actionable work see `MGGRID_TODO.md`.
+
+No formally-tracked issues yet. In-code TODOs are recorded as TODO entries (`GRID-T-*`) in `MGGRID_TODO.md`, since they describe unfinished work rather than confirmed broken behaviour.
+
+Add the first `## GRID-I-1: ...` entry below when a concrete issue is observed.
+
+## Issue entry template
+
+```
+## GRID-I-NN: Short title
+
+**Severity:** Trivial / Low / Minor / Major · **Status:** Open / Documented / Mitigated · **Area:** <subsystem>
+
+### Description
+What breaks, and under what conditions.
+
+### Root cause
+Why it happens (code location + design mismatch).
+
+### Known workaround
+Steps a consumer can take until fixed.
+
+### Related TODO
+`MGGRID_TODO.md#grid-t-NN` (if applicable).
+```

AyCode.Blazor.Components/docs/MGGRID/MGGRID_LAYOUT.md

@@ -1,6 +1,6 @@
 # MgGrid — Layout Persistence
 
-> Part of the MgGrid system. See `MGGRID.md` for overview and component hierarchy.
+> Part of the MgGrid system. See `README.md` for overview and component hierarchy.
 
 ## Storage Keys
 

AyCode.Blazor.Components/docs/MGGRID/MGGRID_PARAMETERS.md

@@ -1,6 +1,6 @@
 # MgGrid — Parameters & Events
 
-> Part of the MgGrid system. See `MGGRID.md` for overview and component hierarchy.
+> Part of the MgGrid system. See `README.md` for overview and component hierarchy.
 
 ## Required Parameters
 
@@ -20,7 +20,7 @@
 | `UpdateMessageTag` | `int` | Tag for "update item" request |
 | `RemoveMessageTag` | `int` | Tag for "remove item" request |
 
-These are bundled into a `SignalRCrudTags` during `OnInitializedAsync`. See `AyCode.Services.Server/docs/SIGNALR_DATASOURCE.md` (in AyCode.Core repo) for details.
+These are bundled into a `SignalRCrudTags` during `OnInitializedAsync`. See `AyCode.Services.Server/docs/SIGNALR/SIGNALR_DATASOURCE.md` (in AyCode.Core repo) for details.
 
 ## Data & Context Parameters
 

AyCode.Blazor.Components/docs/MGGRID/MGGRID_RENDERING.md

@@ -1,6 +1,6 @@
 # MgGrid — Fullscreen & Rendering
 
-> Part of the MgGrid system. See `MGGRID.md` for overview and component hierarchy.
+> Part of the MgGrid system. See `README.md` for overview and component hierarchy.
 
 ## Fullscreen Mode
 

AyCode.Blazor.Components/docs/MGGRID/MGGRID_TODO.md

@@ -0,0 +1,81 @@
+# MGGRID — TODO
+
+For known issues / bugs see `MGGRID_ISSUES.md`.
+
+## Priority legend
+- **P0** blocker · **P1** important · **P2** nice-to-have · **P3** idea
+
+---
+
+## GRID-T-1: Generic ID generation in `MgGridBase.SetNewId`
+**Priority:** P2 · **Type:** Refactor (framework-first) · **Origin:** 2026-04-24 in-code TODO audit · **Area:** `Components/Grids/MgGridBase.cs:460`
+
+`SetNewId(TDataItem dataItem)` branches on `dataItem.Id is Guid` vs `dataItem.Id is int` to produce a new ID, and converts through `TypeConverter` back to `TId`. The in-code comment `//TODO: int !!! - J.` flags this as unfinished — the logic is not cleanly generic over `TId`.
+
+```csharp
+private void SetNewId(TDataItem dataItem)
+{
+    //TODO: int !!! - J.
+    if (dataItem.Id is Guid)
+    {
+        dataItem.Id = (TId)(_typeConverterId.ConvertTo(Guid.NewGuid(), typeof(TId)))!;
+    }
+    else if (dataItem.Id is int)
+    {
+        var newId = -1 * AcDomain.NextUniqueInt32;
+        dataItem.Id = (TId)(_typeConverterId.ConvertTo(newId, typeof(TId)))!;
+    }
+}
+```
+
+Problems:
+- Runtime type switch on a generic parameter defeats the point of generics.
+- Silent no-op for any other `TId` (e.g., `long`, `short`, custom struct) — no compile error, no throw.
+- The negative-int convention (`-1 * AcDomain.NextUniqueInt32`) is not expressed as a contract; consumers cannot override.
+
+### Fix options
+- **(a)** Introduce `IAcNewIdGenerator<TId>` framework abstraction (in AyCode.Core) with default implementations for `Guid` and `int`. `MgGridBase` takes it via DI or generic parameter. Consumer-specific `TId` types register their generator.
+- **(b)** Virtual protected method: `protected virtual TId GenerateNewId()` on `MgGridBase`, with default implementations for `Guid` and `int` preserved. Consumer overrides for custom `TId`.
+- **(c)** Static strategy map keyed by `typeof(TId)` — registered once per app startup, resolved at runtime.
+
+### Acceptance criteria
+- No runtime type-switch in `MgGridBase`.
+- Throws explicit `NotSupportedException` (or similar) for unregistered `TId` types.
+- Existing `Guid` and `int` consumers unaffected.
+- Remove the `//TODO: int !!! - J.` comment.
+
+## GRID-T-2: Implement local grouping in `MgGridSignalRDataSource.GetGroupInfoAsync`
+**Priority:** P3 · **Type:** Feature · **Origin:** 2026-04-24 in-code TODO audit · **Area:** `Components/Grids/MgGridSignalRDataSource.cs:202`
+
+```csharp
+public override async Task<IList<GridCustomDataSourceGroupInfo>> GetGroupInfoAsync(
+    GridCustomDataSourceGroupingOptions options,
+    CancellationToken cancellationToken)
+{
+    _logger?.Debug("[MgGridSignalRDataSource] GetGroupInfoAsync");
+
+    // TODO: Implement local grouping when needed
+    return await base.GetGroupInfoAsync(options, cancellationToken);
+}
+```
+
+Currently delegates to the DevExpress base implementation, which for a server-side `GridCustomDataSource` triggers a server round-trip. With `MgGridSignalRDataSource` already holding a local cache (see `MGGRID_DATASOURCE.md`), grouping over the cached rows would avoid that round-trip.
+
+Not urgent — only light grouping usage so far; the base path works. Promote to P2 if a consumer hits perceptible grouping latency.
+
+### Acceptance criteria
+- Local grouping computed from the cached list when the full dataset is cached.
+- Falls back to base (server) path when the cache is partial / paginated.
+- Unit / integration test with a grouped column.
+- Remove the `// TODO: Implement local grouping when needed` comment.
+
+## TODO entry template
+
+```
+## GRID-T-NN: Short title
+**Priority:** P0 / P1 / P2 / P3 · **Type:** Bug fix / Feature / Refactor / Docs · **Related:** `MGGRID_ISSUES.md#grid-i-NN` (if applicable)
+
+Description of what and why, including the trigger (user request, audit finding, incident).
+
+Options / sub-tasks / acceptance criteria.
+```

AyCode.Blazor.Components/docs/MGGRID/MGGRID_TOOLBAR.md

@@ -1,6 +1,6 @@
 # MgGrid — Toolbar
 
-> Part of the MgGrid system. See `MGGRID.md` for overview and component hierarchy.
+> Part of the MgGrid system. See `README.md` for overview and component hierarchy.
 
 ## MgGridToolbarTemplate
 

AyCode.Blazor.Components/docs/MGGRID/README.md

@@ -2,8 +2,8 @@
 
 > Comprehensive documentation for the **MgGrid** component family — the primary UI data grid pattern in the AyCode.Blazor framework.
 > Source: `Components/Grids/`
-> For SignalR transport: `AyCode.Services/docs/SIGNALR.md` (in AyCode.Core repo)
-> For `AcSignalRDataSource`: `AyCode.Services.Server/docs/SIGNALR_DATASOURCE.md` (in AyCode.Core repo)
+> For SignalR transport: `AyCode.Services/docs/SIGNALR/README.md` (in AyCode.Core repo)
+> For `AcSignalRDataSource`: `AyCode.Services.Server/docs/SIGNALR/SIGNALR_DATASOURCE.md` (in AyCode.Core repo)
 
 ## Overview
 
@@ -28,6 +28,8 @@
 | `MGGRID_TOOLBAR.md` | MgGridToolbarTemplate (buttons, parameters, state) |
 | `MGGRID_COLUMNS.md` | MgGridDataColumn (InfoPanel params, UrlLink) |
 | `MGGRID_DATASOURCE.md` | MgGridSignalRDataSource (server-side data, local cache, background refresh) |
+| `MGGRID_ISSUES.md` | Known issues (`GRID-I-*`, `GRID-B-*`) — currently none formally tracked |
+| `MGGRID_TODO.md` | Planned work (`GRID-T-*`) — refactors, missing features, optimizations |
 
 ## Component Hierarchy
 
@@ -57,7 +59,7 @@ MgGridBase<TSignalRDataSource, TDataItem, TId, TLoggerClient>
 
 | Parameter | Constraint | Purpose |
 |---|---|---|
-| `TSignalRDataSource` | `: AcSignalRDataSource<…>` | SignalR-backed data source (see `AyCode.Services.Server/docs/SIGNALR_DATASOURCE.md` in AyCode.Core repo) |
+| `TSignalRDataSource` | `: AcSignalRDataSource<…>` | SignalR-backed data source (see `AyCode.Services.Server/docs/SIGNALR/SIGNALR_DATASOURCE.md` in AyCode.Core repo) |
 | `TDataItem` | `: class, IId<TId>` | Entity type displayed in the grid |
 | `TId` | `: struct` | Primary key type (`int`, `Guid`) |
 | `TLoggerClient` | `: AcLoggerBase` | Logger for diagnostics |

AyCode.Blazor.Components/docs/README.md

@@ -0,0 +1,16 @@
+# AyCode.Blazor.Components documentation
+
+Topic documentation for the `AyCode.Blazor.Components` project (Blazor component library).
+
+## Topics
+
+- [`MGGRID/`](MGGRID/README.md) — MGGRID data grid component family (CRUD, layout, columns, toolbar, rendering, etc.)
+
+## Navigation
+
+Per the AI Agent Core Protocol (folder navigation rule), start from this README when browsing `docs/`. Each topic folder has its own `README.md` with the main content, plus `TOPIC_*.md` sub-topic files.
+
+## See also
+
+- **Blazor repo conventions**: `../../docs/CONVENTIONS.md`
+- **Architecture overview**: `../../docs/ARCHITECTURE.md`

README.md

@@ -24,7 +24,7 @@ Project-level docs:
 
 | Project | Documents |
 |---|---|
-| `AyCode.Blazor.Components/docs/` | `MGGRID.md` — MgGrid system (grid base, toolbar, InfoPanel, layout, CRUD) |
+| `AyCode.Blazor.Components/docs/` | `MGGRID/` — MgGrid system (grid base, toolbar, InfoPanel, layout, CRUD) |
 
 Core framework rules: `../AyCode.Core/.github/copilot-instructions.md`
 

docs/ARCHITECTURE.md

@@ -49,7 +49,7 @@ User ← DxGrid ← AcSignalRDataSource ← SignalR (AcBinary) ← Server Hub
 
 ## MgGrid Component System
 
-The primary UI pattern for data screens. Overview and index: `AyCode.Blazor.Components/docs/MGGRID.md`
+The primary UI pattern for data screens. Overview and index: `AyCode.Blazor.Components/docs/MGGRID/README.md`
 
 ```
 DxGrid (DevExpress)

docs/GLOSSARY.md

@@ -8,12 +8,12 @@ Blazor/MAUI UI terminology. For core framework terms see `AyCode.Core/docs/GLOSS
 |---|---|
 | **DxGrid** | DevExpress Blazor data grid. Used with `AcSignalRDataSource` for real-time SignalR data. |
 | **CardView** | Card-style layout wrapping DxGrid. Mobile-friendly alternative to table grids. |
-| **AcSignalRDataSource** | Grid data source backed by SignalR. Handles load, CRUD, filtering, and change tracking. See `AyCode.Services.Server/docs/SIGNALR_DATASOURCE.md` in AyCode.Core repo. |
+| **AcSignalRDataSource** | Grid data source backed by SignalR. Handles load, CRUD, filtering, and change tracking. See `AyCode.Services.Server/docs/SIGNALR/SIGNALR_DATASOURCE.md` in AyCode.Core repo. |
 | **AcExpressionNode** | Serializable LINQ expression tree. Grid filters are serialized as expression nodes and sent to server. |
 
 ## MgGrid System
 
-For full technical reference see `AyCode.Blazor.Components/docs/MGGRID.md`.
+For full technical reference see `AyCode.Blazor.Components/docs/MGGRID/README.md`.
 
 | Term | Definition |
 |---|---|
@@ -26,7 +26,7 @@ For full technical reference see `AyCode.Blazor.Components/docs/MGGRID.md`.
 | **MgGridSignalRDataSource** | `GridCustomDataSource` wrapping `AcSignalRDataSource`. Local cache, background refresh. |
 | **IMgGridBase** | Public interface: `IsSyncing`, `GridEditState`, `ParentGrid`, `StepPrevRow/NextRow`, layout persistence methods. |
 | **MgGridEditState** | Enum: `None` (no edit), `New` (adding item), `Edit` (modifying item). |
-| **SignalRCrudTags** | Bundle of 5 integer message tags (GetAll, GetItem, Add, Update, Remove) for one entity type. See `AyCode.Services.Server/docs/SIGNALR_DATASOURCE.md` in AyCode.Core repo. |
+| **SignalRCrudTags** | Bundle of 5 integer message tags (GetAll, GetItem, Add, Update, Remove) for one entity type. See `AyCode.Services.Server/docs/SIGNALR/SIGNALR_DATASOURCE.md` in AyCode.Core repo. |
 | **IsMasterGrid** | `true` when `ParentDataItem == null` — top-level grid (not detail). |
 | **AutoSaveLayoutName** | Base name for localStorage layout keys. Default: `"Grid{TDataItem.Name}"`. |
 

docs/README.md

@@ -0,0 +1,23 @@
+# AyCode.Blazor documentation
+
+Top-level documentation for the `AyCode.Blazor` repo (Blazor/MAUI UI framework — Layer 1).
+
+## Reference docs (flat)
+
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — Repo architecture overview
+- [`CONVENTIONS.md`](CONVENTIONS.md) — Coding conventions
+- [`GLOSSARY.md`](GLOSSARY.md) — Domain glossary
+
+## Topic folders
+
+Topic-specific documentation lives at the sub-project level:
+
+- **MGGRID** (data grid component family): `../AyCode.Blazor.Components/docs/MGGRID/README.md`
+
+## Navigation
+
+Per the AI Agent Core Protocol (folder navigation rule), start from this README when browsing `docs/`. Single-file reference docs remain flat at this level; multi-file topics live in named subfolders.
+
+## See also
+
+- **Base framework docs**: `../../AyCode.Core/docs/README.md` (if present) and per-project `docs/` folders under AyCode.Core.