diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 9e3e6c1..774113e 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -61,6 +61,30 @@ Skills defined in other repos that can be referenced from here:
   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.
 
+## Framework-First Design Principle
+
+🛑 **This repo is framework (Layer 1 — UI framework), not a consumer application.** Depends on Layer 0 (AyCode.Core), consumed by Layer 2/3.
+
+**Before writing code, ask:**
+1. Generic (reusable across any consumer)? → belongs HERE
+2. Consumer-specific (business logic, URLs, product names)? → NOT HERE
+3. Same pattern in 2+ consumers? → promote to framework
+
+**Hard rules:**
+- ❌ No consumer names or product-specific terms in code, identifiers, or docs
+- ❌ No framework → consumer references
+- ✅ Abstract/virtual base classes with generic type parameters for consumer types
+- ✅ `IOptions<T>` for per-consumer configuration
+
+**Blazor/MAUI-specific emphasis:**
+- UI components use generic type parameters (consumer types) — never hardcode
+- DevExpress wrappers stay generic — framework composes, consumer extends
+- MAUI platform folders (`AyCode.Maui.Core/Platforms/`) = platform abstractions only, not consumer-app-specific code (manifest, splash screens, app assets belong in consumer app)
+
+Framework design = **"write the base first, derive the specific later"**.
+
+Full doctrine: `../AyCode.Core/.github/copilot-instructions.md#framework-first-design-principle` and `docs/ARCHITECTURE.md#framework-vs-consumer-boundary`.
+
 ## DevExpress Components
 1. **DevExpress Blazor 25.1.3** — always use `DxGrid`, `DxFormLayout`, etc. Do NOT mix with generic Blazor component libraries.
 2. **Grid system** uses `AcSignalRDataSource` for real-time data — grids fetch data via SignalR, not REST.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 2d72b67..e36abd3 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,5 +1,16 @@
 # Architecture
 
+## Framework vs. Consumer Boundary
+
+This is **Layer 1 — UI framework**, building on Layer 0 (AyCode.Core) and consumed by Layer 2/3 projects. Full doctrine: `../AyCode.Core/docs/ARCHITECTURE.md#framework-vs-consumer-boundary`.
+
+### Blazor/MAUI-specific notes
+
+- Components use **generic type parameters** for consumer types (e.g. the MgGrid generic hierarchy)
+- DevExpress wrappers stay generic — no consumer-entity specialization in framework components
+- MAUI platform folders (`AyCode.Maui.Core/Platforms/`) provide platform abstractions only; consumer-app manifest / splash screens / app-specific assets belong in the consumer app
+- UI patterns maximize **generic base + consumer derives**
+
 ## Dependency Graph
 
 ```
diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md
index d1993cc..05c847d 100644
--- a/docs/CONVENTIONS.md
+++ b/docs/CONVENTIONS.md
@@ -2,6 +2,15 @@
 
 For core framework conventions (Ac prefix, Session/Transaction pattern, etc.) see `AyCode.Core/docs/CONVENTIONS.md`.
 
+## Framework-First Placement
+
+Follow the doctrine in `../AyCode.Core/docs/CONVENTIONS.md#framework-first-placement`. Same verdicts and hard rules apply.
+
+**Blazor/MAUI-specific additions:**
+- UI types follow the generic-base pattern — consumer types are type parameters, not hardcoded concrete types
+- DevExpress-wrapper components stay generic across consumers
+- MAUI platform code = platform abstractions only, not consumer-app specifics
+
 ## Naming
 
 - **Grid components:** `Grid{Entity}Base` (e.g., `GridPartnerBase`, `GridShippingBase`). Suffix `Base` because consuming projects may extend them.