docs: clarify evaluation and resolution details

Author: Rul1an

specification/types.md

@@ -32,7 +32,7 @@ A language primitive for representing a date and time, optionally including time
 
 ### Evaluation Details
 
-A structure representing the result of the [flag evaluation process](./glossary.md#evaluating-flag-values), and made available in the [detailed flag resolution functions](./sections/01-flag-evaluation.md#14-detailed-flag-evaluation), containing the following fields:
+A structure representing the result of the [flag evaluation process](./glossary.md#evaluating-flag-values), and made available in the [detailed flag evaluation functions](./sections/01-flag-evaluation.md#14-detailed-flag-evaluation), containing the following fields:
 
 - flag key (string, required)
 - value (boolean | string | number | structure, required)
@@ -47,6 +47,10 @@ A structure representing the result of the [flag evaluation process](./glossary.
 > For example, in the case of an unsuccessful evaluation, `error code`, `reason`, and `error message` will be set, and `variant` will not.
 > If the type system of the implementation supports the expression of such constraints, consider defining them.
 
+> [!NOTE]
+> `evaluation details` are the application-facing result returned from detailed flag evaluation.
+> They include the `flag key` supplied to the client, the evaluated value, and metadata derived from the provider's `resolution details` when available.
+
 ### Resolution Details
 
 A structure which contains a subset of the fields defined in the `evaluation details`, representing the result of the provider's [flag resolution process](./glossary.md#resolving-flag-values), including:
@@ -97,8 +101,9 @@ let myReason = Reason::Other("my-reason".to_string());
 ```
 
 > [!NOTE]
-> The `resolution details` structure is not exposed to the Application Author.
-> It defines the data which Provider Authors must return when resolving the value of flags.
+> `resolution details` are the provider-to-SDK return shape.
+> Provider Authors return this structure to the SDK when resolving a flag value.
+> Application Authors do not receive the actual `resolution details` object directly; instead, detailed evaluation methods return an `evaluation details` object built from the resolution result plus SDK-level fields such as `flag key` and default or error handling.
 
 ### Error Code