Mango.Nop.Libraries/.github/copilot-instructions.md

# Mango.Nop Libraries — Domain Rules

## 🛑 AI AGENT CORE PROTOCOL (CRITICAL ENFORCEMENT)
You are operating in a multi-repo, documentation-first architecture. You MUST STRICTLY follow this protocol for every response. Failure to do so will break the workspace rules.

1. **MANDATORY OUTPUT PREFIX:** Your response MUST begin on the very first line with this format:
   `[LOADED_DOCS: N files (+K this turn: <comma-separated short names>)]`
   - `N` = total count of `.md` files currently in your context (across all loaded docs in this conversation)
   - `K` = count of `.md` files newly loaded during THIS response (may be 0)
   - If `K > 0`: list the newly loaded files as **shortest unique short names** (see naming rule below)
   - If `K = 0`: write `[LOADED_DOCS: N files, no new loads]`
   - If `N = 0`: write `[LOADED_DOCS: NONE]`

   **Short-name rule (for each loaded `.md` file):**
   - **Default:** use the basename only. Works for all topic-prefixed companions (`LOGGING_ISSUES.md`, `BINARY_FEATURES.md`) and flat single-file topics (`ARCHITECTURE.md`, `GLOSSARY.md`, `CONVENTIONS.md`) — these are already unique.
   - **For `README.md` files:** always include the immediate parent folder as prefix → `TOPIC/README.md` (e.g., `LOGGING/README.md`, `BINARY/README.md`). Never write a bare `README.md` in the prefix because multiple folders have one.
   - **Cross-project disambiguation:** if two files share the same short name (rare — e.g., `docs/README.md` from two different projects), extend the prefix one more level: `PROJECT/docs/README.md`. Always use the shortest unique form.
   - **Never use absolute paths.** Never include the `.github/` prefix for `copilot-instructions.md` — the `.github/` location is implicit. When multiple are loaded simultaneously (typical in `protocol-audit`), apply the cross-project disambiguation above: `AyCode.Core/copilot-instructions.md`, `FruitBankHybridApp/copilot-instructions.md`, etc.

   **Examples:**
   - `[LOADED_DOCS: NONE]` — nothing loaded yet
   - `[LOADED_DOCS: 1 files, no new loads]` — only `copilot-instructions.md` loaded earlier, nothing new this turn
   - `[LOADED_DOCS: 4 files (+3 this turn: LOGGING/README.md, LOGGING_ISSUES.md, LOGGING_TODO.md)]` — logger topic folder loaded
   - `[LOADED_DOCS: 7 files (+3 this turn: SIGNALR/README.md, SIGNALR_ISSUES.md, SIGNALR_TODO.md)]` — SignalR topic loaded (LOGGING was already in context)
   - `[LOADED_DOCS: 5 files (+2 this turn: ARCHITECTURE.md, GLOSSARY.md)]` — top-level reference docs loaded (flat, no folder prefix needed)

   This prefix is MANDATORY on **EVERY** response (not just the first, not just when loading happens). It serves two purposes: **(a)** user-visible compliance signal, and **(b)** self-commitment for the no-re-read rule — in subsequent turns you read your own prior prefix from the conversation to enforce Rule #3. Dropping the prefix breaks both.

2. **HARD-GATE DELAY (DOCS BEFORE CODE) & TOOL EXECUTION BLOCK:** 
   - If `[LOADED_DOCS: NONE]` applies, you **MUST STOP** and you are **STRICTLY FORBIDDEN** to use the following tools: `code_search`, `get_symbols_by_name`, `find_symbol`, or `get_file` (for non-markdown files).
   - Your VERY FIRST AND ONLY allowed tool calls must be `file_search` or `get_file` targeting the `.md` documentation in the relevant `docs/` folders or `README.md`.
   - Do not answer the user's core question until the `[LOADED_DOCS]` list is populated with the base architecture files.
   - **CRITICAL EXCEPTION:** Do **NOT** re-read `.md` files that are already mapped in your context or `LOADED_DOCS` list (strictly maintain rule 3).
   - **CROSS-REPO HARD-GATE:** When navigating to an external repo (via `own-dep-repos` paths), read that repo's `docs/` and `README.md` BEFORE searching its source code. The hard-gate applies to EVERY repo you enter, not just your own.
   - **PER-QUESTION DOC-FIRST:** Before searching source code for any user question, check whether there is a relevant `.md` file (folder `README.md`, other repo `docs/`, etc.) that has NOT yet been loaded. Read it first — it tells you where to look in the code, saving searches and tokens. Only after loading relevant docs should you search/read source files.

3. **STRICT NO-RE-READ POLICY (ANTI-LOOP):**
   You are PHYSICALLY FORBIDDEN from calling `get_file` or `file_search` on any `.md` file that is already listed in your `[LOADED_DOCS]` prefix. 
   - **Definition:** A doc is "in your context" ONLY if you have read its actual file content via a tool call in THIS conversation. Prior session summaries, compacted messages, and memory entries do NOT count — they are lossy compressions.
   - Once an `.md` file is in your context, it STAYS in your context.
   - Re-reading them wastes tokens and breaks the protocol. 
   - ONLY re-read an `.md` file if the user EXPLICITLY states "the file has changed on disk, read it again". 
   - If the user simply mentions a glossary term or requests info found in a loaded doc, answer directly from memory. DO NOT search for it again.

4. **CONTEXT RECOVERY (SMART READ):**
   If the user asks a domain/architecture specific question and you realize the essential `.md` files are NO LONGER in your current context (they dropped out of memory), you **MUST automatically re-read** the necessary documentation before answering. 
   Do NOT wait for the user to explicitly tell you to re-read them. Prioritize scanning the `docs/` folders to recover the lost context.

   **Auto-detection triggers (MUST treat ALL docs as NOT loaded):**
   - Session starts with a summary of a previous conversation (context recovery/compaction)
   - Message compaction or context compression occurred mid-session
   - You cannot quote the exact content of a doc you claim to know
   When any trigger fires → reset `[LOADED_DOCS: NONE]` and re-read per Rule #2.

   Directories to read (when recovering context):
   - `docs/` (in this repository root)

5. **EXPLICIT CONSENT FOR MODIFICATIONS:**
   NEVER rewrite, create, or delete any file (code, documentation, configuration, memory, or otherwise) without the user's explicit permission. If the user does not specifically request a code modification (e.g., using phrases like "we are just thinking," "what do you think," "let's plan"), you MUST ONLY provide text-based analysis and planning. You are FORBIDDEN from using file-modifying tools (`replace_string_in_file`, `edit_file`, `create_file`, etc.) until the user explicitly says "ok", "go ahead", "implement", or a similar unambiguous approval.

6. **AUTHORITY, RULE SCOPE, AND SKILL INVOCATION:**
   When proposing structural changes (new files, conventions, categories, IDs, naming patterns, URL schemes, etc.), follow these three principles:

   - **Authority before proposal:** Before proposing new structures, conventions, categories, or IDs, verify the proposal against the **authoritative source** for that domain. If a registry, convention doc, or canonical reference exists, follow it (or its registered maintenance workflow for new entries). Do not invent ad-hoc when an authority exists.

   - **Rule implications are part of the rule:** Rules have **scope implications** beyond their literal text. Apply rules **conservatively** — if a rule prohibits action X, do not work around it with novel patterns Y that achieve the same effect. Working around rule scope with ad-hoc patterns is a process violation, not a creative solution.

   - **Skill invocation preferred over reimplementation:** If a workspace skill's scope covers the current task, **invoke the skill explicitly** rather than manually performing similar steps. Skills canonicalize subtleties (validation rules, cross-references, edge cases) that ad-hoc reimplementation risks missing. Improvising a skill's logic is a process violation.

## Session Setup

**Mandatory reads at session start** — in addition to this `copilot-instructions.md`, the agent MUST load the **two reactive workspace skills' `SKILL.md` files** (the three user-gated skills are lazy-loaded on demand — see notes below):

- `docs-discovery/SKILL.md` — **reactive** (triggers on any domain question — must be ready BEFORE the first domain query arrives)
- `docs-check/SKILL.md` — **reactive** (triggers at the end of every code-modifying response)

The remaining three skills are **lazy-loaded** — `SKILL.md` is read on demand at invocation, not at session start. The 1-2 line summaries in `## Shared Agent Skills` below are sufficient for trigger recognition; the full skill content loads only when needed:

- `protocol-audit/SKILL.md` — user-invoked ("audit protocol"); LLM-suggest-back when a `.github/copilot-instructions.md` or `SKILL.md` is modified during the session.
- `adr-author/SKILL.md` — user-invoked ("let's plan X", "design Y"); LLM-suggest-back on ADR-worthy conversation drift.
- `docs-archive/SKILL.md` — user-invoked ("archive ISSUES", "rotate logs"); LLM-suggest-back when active `_ISSUES.md` / `_TODO.md` / DEC log shows many closed prior entries.

**Path resolution**: if this repo is the canonical protocol host (see `@repo` block below — typically AyCode.Core), the paths are local: `.github/skills/<skill>/SKILL.md`. Otherwise, prefix with this repo's `own-dep-repos` AyCode.Core path (see the `## Shared Agent Skills` section below for explicit paths).

**Why mandatory**: workspace skills live as plain `SKILL.md` files in `.github/skills/` — LLMs do NOT auto-discover them via any built-in skill-registry. Without pre-loading their `SKILL.md` content, the agent cannot reliably recognize implicit triggers (e.g., "domain question → invoke docs-discovery" at the moment the question arrives, not retroactively). Pre-loading is a **one-time cost** per session (~5-8K tokens for the 2 reactive `SKILL.md` files; the 3 user-gated skills are lazy-loaded — no upfront cost); Rule #3 (no-re-read) prevents repeated reads; re-read only if Rule #4 (Context Recovery) fires.

**Amortization — critical, do NOT re-evaluate per-turn**: the Session Setup cost is measured over the ENTIRE session, not per single turn. A typical session has many turns; the first domain question alone already recoups the investment (alternative — repeated source-code `Grep`/`Read` per turn — costs 10-20K tokens *per turn* with lower output quality). Do NOT flag pre-loaded content as "wasteful" for turns that don't invoke it — the design depends on cross-turn amortization + Rule #3 (no-re-read) + on-demand specificity of Rule #4 (Context Recovery). This amortization is the **central token-economics principle** of the entire protocol stack.

The first response's `[LOADED_DOCS: ...]` prefix must reflect **3 files** (this `copilot-instructions.md` + 2 reactive SKILL.md). Lazy-loaded skills add to the count when invoked.

## Workspace Dependencies
# own-dep-repos: "name: path" — paths are relative to this repo root (.github/..)
@repo {
  name = "Mango.Nop Libraries"
  prefix = "MGNOPLIB"
  type = "framework"
  layer = 1
  own-dep-repos = ["AyCode.Core: ../../../../../Aycode/Source/AyCode.Core"]
}

> This is the **single source of truth** for Mango.Nop library rules. Do not duplicate these elsewhere.
> For detailed docs see: `README.md` → `docs/`
> For core framework rules see: `.github/copilot-instructions.md` (in AyCode.Core repo)
> External repos in `own-dep-repos` are fully accessible — read their source code, docs, and `.github/copilot-instructions.md` freely when you need type definitions, base classes, or context. Do not limit yourself to the current workspace.

## Shared Agent Skills

Skills defined in other repos. **Two reactive skills are pre-loaded at session start; three user-gated skills are lazy-loaded on demand** — see `## Session Setup` above for the load matrix:

- **protocol-audit** — Cross-repo consistency audit for `.github/copilot-instructions.md` across all 5 repos.
  Location: `AyCode.Core/.github/skills/protocol-audit/SKILL.md`
  Activate from an AyCode.Core session, or read the SKILL.md directly and follow its steps.

- **docs-discovery** — Load relevant `.md` documentation (main + `_ISSUES` + `_TODO` paired sets) BEFORE source-code search or modifications. Saves tokens vs. grep-based rediscovery.
  Location: `AyCode.Core/.github/skills/docs-discovery/SKILL.md` (see `own-dep-repos` above for the relative path to AyCode.Core)
  **Invoke proactively** before any domain-related coding task (see "Documentation-first coding" below). Honours the active repo's **no-re-read** rule.

- **docs-check** — Evaluate loaded `.md` files at the end of every code-modifying response: drift vs code, missing topic coverage, csproj-glob registration gaps for new `.md` files, and new issue/TODO candidates. Emits the `[DOCUMENTATION CHECK]` section.
  Location: `AyCode.Core/.github/skills/docs-check/SKILL.md`
  **Invoke at the end of every code-modifying response.** Read-only on loaded docs; all patches surface as proposals (Rule #5 approval required).

- **adr-author** — Create Architecture Decision Records (ADRs) for architecturally significant design decisions. Structured interview (context → alternatives → trade-offs → decision → consequences) producing a durable `docs/adr/NNNN-<slug>.md` file (product decisions) or a new `LLMP-DEC-N` row in the protocol decision log (meta-protocol decisions).
  Location: `AyCode.Core/.github/skills/adr-author/SKILL.md`
  **Invoke on explicit user request** ("let's plan X", "decide Y vs Z", "design the W module") **or proactively flag** when the conversation looks ADR-worthy (user must confirm — never auto-invoke).

- **docs-archive** — Rotate closed entries (Status: Fixed/Resolved/Won't fix/Superseded by X) from active `_ISSUES.md`, `_TODO.md`, and `LLM_PROTOCOL_DECISIONS.md` into year-bucketed archive companions (`*_<year>.md`). Year of the Status update determines destination file. Active files retain only Open/Partially Fixed entries plus a pointer to the archives. Archive files are NOT auto-loaded — agents read them on-demand when historical context becomes relevant.
  Location: `AyCode.Core/.github/skills/docs-archive/SKILL.md`
  **Invoke on explicit user request** ("archive ISSUES", "rotate logs") **or proactively flag** when an active artifact file has many closed prior entries (user must confirm — never auto-invoke).

## Protocol History

Cumulative log of LLM-protocol decisions (rule changes, new skills, structural shifts):

- `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md`

Read this file when you need to understand **why** a rule is the way it is, or before proposing a protocol change — it may save a debate about something already resolved.

## Documentation-first coding

Before running any source-code `Grep` / `get_file` / `code_search` in response to a domain-related request, invoke the **`docs-discovery`** skill (path above). Scans `docs/` folders in THIS repo AND in referenced repos (via `own-dep-repos`) via Glob, loads paired .md sets as a unit. Rule-number-agnostic — refers to rule NAMES (no-re-read, folder-navigation, explicit-consent) which are stable across repos.

## nopCommerce Compatibility
1. All three libraries target **net9.0** — required by nopCommerce 4.80.9. Do NOT change TFM.
2. **NopDependencies** folder in `Mango.Nop.Core` contains **mirror copies** of nopCommerce entity classes (`BaseEntity`, `Customer`, `Order`, `Product`, `GenericAttribute`, etc.) so that `Mango.Nop.Core` can be referenced without the full nopCommerce dependency chain.
3. Do NOT modify files in `NopDependencies/` unless the nopCommerce version changes.

## Entity & DTO Patterns
4. **`BaseEntity`** (NopDependencies) = root entity base with `int Id` and `IBaseEntity` interface. All nopCommerce entities inherit from this. Namespace: `Nop.Core`.
5. **`MgEntityBase`** = custom entity base that inherits `BaseEntity` and implements `IEntityInt` (from AyCode.Interfaces). Used for domain-specific entities and complex DTOs.
6. **Two DTO base strategies exist:**
   - `ModelDtoBase<TMainEntity>` — for simple DTOs (e.g. `CustomerDto`). Manual `CopyEntityValuesToDto`/`CopyDtoValuesToEntity` overrides. Uses `Activator.CreateInstance<T>()` in `CreateMainEntity()`.
   - `MgEntityBase` + `IModelDtoBase<T>` — for complex DTOs with LinqToDB `[Association]` navigations (e.g. `MgOrderDto`, `MgOrderItemDto`). Uses `PropertyHelper.CopyPublicValueTypeProperties()` for automatic value-type copy.
7. **`GenericAttribute`** = polymorphic key-value store. `KeyGroup` = owner type name, `EntityId` = owner ID, `Key` = attribute name, `Value` = string value. Use `GenericAttributeExtensions.GetValueOrNull<T>()`/`GetValueOrDefault<T>()`/`TryGetValue<T>()` — never parse raw strings manually.

## Data Access Patterns
8. **`MgDbTableBase<TEntity>`** = repository base wrapping nopCommerce `EntityRepository<TEntity>`. Adds `GetAll()` (`IQueryable<T>`), automatic timestamp handling (`ITimeStampCreated`/`ITimeStampModified`), virtual CRUD hooks (`OnInsert`/`OnUpdate`/`OnDelete`).
9. **`MgDtoDbTableBase<TDtoEntity, TMainEntity>`** = DTO-aware repository. **CRITICAL: All Delete methods throw — always use `DeleteMainEntityById(int id)`.** Event bridging: DTO insert/update events → main entity events.
10. **`MgDbContextBase`** = DB context base (NOT EF Core DbContext — wraps `INopDataProvider` and `IRepository<T>` nopCommerce repos). Provides `Transaction`/`TransactionSafe`/`TransactionAsync`/`TransactionSafeAsync`. TransactionSafe variants use global `SemaphoreSlim` lock for serialized access.

## Service Patterns
11. **`MgBackgroundServiceBase`** — inherits `Microsoft.Extensions.Hosting.BackgroundService`. Loop: `Task.Delay(interval)` → `OnExecuteAsync()`. Pause support. Per-iteration exception handling. **Uses nopCommerce `Nop.Services.Logging.ILogger`** (not Mango logger).
12. **`MgEventConsumerBase`** — subscribes to `EntityUpdatedEvent<Product>`, `EntityInsertedEvent<Product>`, `CustomerRegisteredEvent`, `OrderPlacedEvent`, `PageRenderingEvent`, `ProductSearchEvent`. Override relevant handlers. Built-in: `CheckAndUpdateProductManageInventoryMethodToManageStock()`.
13. **`NopLogWriter`** — AyCode → nopCommerce log bridge. Log level mapping: `Detail/Trace/Debug/Info` → `Information`; `Suggest/Warning` → `Warning`; `Error` → `Error`. Uses `TransactionScope(Suppress)` to avoid nesting.

## Conventions
14. **`Mg` prefix** for all custom types: `MgEntityBase`, `MgOrderDto`, `MgDbTableBase`, etc.
15. **No redundant code** — before writing new logic, check whether similar methods already exist in the current context. Reuse or extract shared logic.
16. **Keep all .md documentation in sync** — at the end of EVERY code-modifying response, invoke the **`docs-check`** skill (`AyCode.Core/.github/skills/docs-check/SKILL.md`). It evaluates loaded `.md` files for drift vs code, missing topic coverage, csproj-glob registration gaps for new `.md` files, and new issue/TODO candidates — then emits the `[DOCUMENTATION CHECK]` section per its procedure (or `[DOCUMENTATION CHECK] None.` single-line when nothing to report). The skill encapsulates the full calibration (4 prerequisites, 3-item volume cap, no-ID rule, status-update-on-fix clause) and empty-state handling. Passive detection + ASK FIRST; all patches require user approval (Rule #5). Do NOT trigger new searches for this check.
17. All AyCode references are via **DLL** (not ProjectReference) — this is intentional. **AyCode.Core** solution (`../../../../../Aycode/Source/AyCode.Core/`) contains all core framework code: interfaces, serialization, binary protocol, SignalR base classes, data sources, logging. Types not defined in this library (e.g. `IEntityInt`, `IId<T>`, `AcConst`, `ToonDescription`) likely live in AyCode.Core.
18. **Do not re-read .md files** already in your context window. They only change if you modify them yourself (new content is already in context) or if the developer tells you they changed — in that case re-read them once.
19. **Folder navigation** — start from the root `README.md` for solution-level navigation. When you need to understand a folder's contents or find a type/class, read the `README.md` in that folder first — it indexes the local files and sub-folders. Follow this before grepping or reading source files.
20. **Documentation layering** — write `.md` documentation at the **defining layer** (where the code lives). Higher-layer `.md` files reference AyCode.Core base docs using the form `../../../../../Aycode/Source/AyCode.Core/{Project}/docs/FILENAME.md`. Document only project-specific overrides or extensions. Never duplicate base-layer descriptions in consumer-level docs.
21. **LinqToDB associations** — use `[Association(ThisKey = nameof(FK), OtherKey = nameof(Target.Id), CanBeNull = true/false)]` for navigation properties in DTOs.
22. **Timestamp auto-management** — entities with `ITimeStampCreated` or `ITimeStampModified` get automatic UTC timestamps in `MgDbTableBase` CRUD hooks. Don't set these manually.

## Reference Modes
- **Full stack** (ProjectReference, all 3 libraries) — for nopCommerce plugins needing entity access, data layer, and services.
- **Types only** (DLL reference, `Mango.Nop.Core` only) — for projects that only need DTOs, entities, and interfaces without the nopCommerce runtime dependency.