diff --git a/design.md b/design.md
index 82c70b6..fe47c7f 100644
--- a/design.md
+++ b/design.md
@@ -10,9 +10,18 @@ Divided into identifer bits and version bits.
 
 ## Component
 
-c# structs marked for [MessagePack](https://github.com/MessagePack-CSharp/MessagePack-CSharp) serialization.
+C# structs/classes marked with `[MessagePackObject]` and `[Key]` attributes for
+[MessagePack-CSharp](https://github.com/MessagePack-CSharp/MessagePack-CSharp) serialization.
 
-Components are in sparse-sets so they can cheaply be added/removed.
+- Types must be `public` — MessagePack requires public accessibility.
+- Use indexed integer keys (`[Key(0)]`) for best performance and smallest binary
+  size. String keys are available for debugging/interop but slower.
+- For contractless usage, `[MessagePackObject(keyAsPropertyName: true)]` is
+  available.
+- The `MessagePackAnalyzer` package provides compile-time validation and AOT-safe
+  source-generated formatters.
+
+Components are stored in sparse-sets so they can cheaply be added/removed.
 
 ## Relationship
 
diff --git a/docs/architecture.md b/docs/architecture.md
index daabbd0..2c2e024 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -334,3 +334,32 @@ no parallel scheduling.
 
 - Consumers must be on .NET 8 or later.
 - Can use `ref` returns, `readonly struct`, and other modern C# features.
+
+---
+
+## ADR-012: Public Types Required for MessagePack Serialization
+
+**Status:** Accepted
+
+**Context:** Component types must be serializable by MessagePack-CSharp. The
+library imposes constraints on type design.
+
+**Decision:** Component types must be `public` and annotated with
+`[MessagePackObject]` and `[Key]` attributes. The `MessagePackAnalyzer` NuGet
+package is included for compile-time validation.
+
+**Rationale:**
+
+- MessagePack-CSharp requires public types for its dynamic formatter generation
+  and source-generated formatters.
+- `MessagePackAnalyzer` provides AOT-safe source-generated formatters (critical
+  for Unity IL2CPP) and catches misconfigured types at compile time.
+- Indexed integer keys (`[Key(0)]`) produce the fastest and most compact
+  serialization, which aligns with the ECS performance goal.
+
+**Consequences:**
+
+- Component authors cannot use `private` or `internal` types.
+- The `MessagePackAnalyzer` package is a compile-time dependency.
+- `[Key]` indices should be sequential starting from 0 to avoid null
+  placeholders in the binary output.
diff --git a/src/OECS/OECS.csproj b/src/OECS/OECS.csproj
index d1a65b4..1ddefd9 100644
--- a/src/OECS/OECS.csproj
+++ b/src/OECS/OECS.csproj
@@ -15,7 +15,11 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="MessagePack" Version="3.1.3" />
+    <PackageReference Include="MessagePack" Version="3.1.7" />
+    <PackageReference Include="MessagePackAnalyzer" Version="3.1.7">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
     <PackageReference Include="R3" Version="1.2.9" />
   </ItemGroup>