diff --git a/gateway.md b/gateway.md
index 391f5a5..cc7047d 100644
--- a/gateway.md
+++ b/gateway.md
@@ -649,6 +649,49 @@ The exact field names should be adjusted to match the actual interop struct,
 but the design principle is important: do not collapse status arrays into a
 single success flag.
 
+### MxStatus Detail Vocabulary
+
+`MxStatusProxy.detail` carries MXAccess's `MxStatusDetail` code verbatim. The
+vocabulary below is lifted from the installed toolkit's interop enum
+(`Interop.aaMxDataConsumer` → `MxStatusDetail`, confirmed against the
+`MxNativeCodec/MxStatus.cs` map in the MXAccess analysis project — see
+`docs/DesignDecisions.md` external sources). Consumers mapping statuses onto
+another protocol (e.g. OtOpcUa's OPC UA status mapping) should key on these
+codes rather than truncating or banding the raw value:
+
+| Detail | Name | Detail | Name |
+|---|---|---|---|
+| 0 | `MX_S_Success` | 1003 | `MX_E_IndexOutOfRange` |
+| 1 | `MX_E_RequestTimedOut` | 1004 | `MX_E_DataOutOfRange` |
+| 2 | `MX_E_PlatformCommunicationError` | 1005 | `MX_E_IncorrectDataType` |
+| 3 | `MX_E_InvalidPlatformId` | 1006 | `MX_E_NotReadable` |
+| 4 | `MX_E_InvalidEngineId` | 1007 | `MX_E_NotWriteable` |
+| 5 | `MX_E_EngineCommunicationError` | 1008 | `MX_E_WriteAccessDenied` |
+| 6 | `MX_E_InvalidReference` | 1009 | `MX_E_UnknownError` |
+| 7 | `MX_E_NoGalaxyRepository` | 1010 | `MX_E_ObjectInitializing` |
+| 8 | `MX_E_InvalidObjectId` | 1011 | `MX_E_EngineInitializing` |
+| 9 | `MX_E_ObjectSignatureMismatch` | 1012 | `MX_E_SecuredWrite` |
+| 10 | `MX_E_AttributeSignatureMismatch` | 1013 | `MX_E_VerifiedWrite` |
+| 11 | `MX_E_ResolvingAttribute` | 1014 | `MX_E_NoAlarmAckPrivilege` |
+| 12 | `MX_E_ResolvingObject` | 1015 | `MX_E_AlarmAckedAlready` |
+| 13 | `MX_E_WrongDataType` | 1016 | `MX_E_UserNotHavingAccessRights` |
+| 14 | `MX_E_WrongNumberOfDimensions` | 1017 | `MX_E_VerifierNotHavingVerifyRights` |
+| 15 | `MX_E_InvalidIndex` | 8000 | `MX_E_AutomationObjectSpecificError` |
+| 16 | `MX_E_IndexOutOfOrder` | 1000 | `MX_E_InvalidPrimitiveId` |
+| 17 | `MX_E_DimensionDoesNotExist` | 1001 | `MX_E_InvalidAttributeId` |
+| 18 | `MX_E_ConversionNotSupported` | 1002 | `MX_E_InvalidPropertyId` |
+| 19 | `MX_E_UnableToConvertString` | 25 | `MX_E_GalaxyRepositoryBusy` |
+| 20 | `MX_E_Overflow` | 26 | `MX_E_EngineOverloaded` |
+| 21 | `MX_E_NmxVersionMismatch` | 23 | `MX_E_LmxVersionMismatch` |
+| 22 | `MX_E_NmxInvalidCommand` | 24 | `MX_E_LmxInvalidCommand` |
+
+Codes observed live in write-completion correlation: `1007`
+(`MX_E_NotWriteable` — write to a read-only attribute) and `1008`
+(`MX_E_WriteAccessDenied` — e.g. a write through a plain-advised handle that
+lacks supervisory access). `1012`/`1013` mark attributes classified for
+secured/verified writes; `1016`/`1017` are the secured-write credential
+failures.
+
 For command replies, return:
 
 - protocol status,