Reduce entity lookup context and configure reasoning effort

docs/llm-context-efficiency-v1.md

@@ -0,0 +1,42 @@
+# Identity context and reasoning configuration
+
+Entity-resolution protocol 3 omits sources of kind `unread_reference` and
+`fact_reference` from plan and assessment messages. Those sources cannot ground
+identity searches. All readable sources (including human observations, reports,
+quest descriptions, entities, technical facts and uncertainty) remain unchanged.
+Assessment retains all candidates, captures, truncation and coverage information.
+No canonical case data or archive member is removed. Final interpretation is unchanged.
+The full context remains persisted; protocol 1/2 reconstruct their original requests.
+New cases select protocol 3. Existing cases keep their frozen protocol, so use a
+fresh trial to measure the reduced prompts.
+
+On the quality-diagnostics-20261015 sample, message characters fall from 130430
+to 44913 for planning (65.6%) and from 137708 to 52191 for assessment (62.1%).
+These are offline character measurements, not measured API tokens or cost savings.
+No LLM quality equivalence is claimed before a fresh live trial.
+
+## Provider settings
+
+`max_output_tokens` already configures the output limit using `token_parameter`.
+Optional `reasoning_effort` is now forwarded as a top-level chat-completions field.
+Allowed values: `none`, `minimal`, `low`, `medium`, `high`; actual support depends
+on provider/model. Omission preserves provider defaults and historical configuration
+snapshot hashes. An explicit value is part of the persisted configuration snapshot.
+There is no automatic downgrade or silent retry when a provider rejects a setting.
+This is a reasoning level, not an exact thinking-token quota. It does not change
+investigation credits, API account credit, timeout or package-format limits.
+
+Google documents support and model-dependent mapping here:
+https://ai.google.dev/gemini-api/docs/openai#thinking
+
+Example provider settings for the next quality trial:
+
+```toml
+max_output_tokens = 16384
+reasoning_effort = "medium"
+```
+
+The output limit is a ceiling, not a request to generate that many tokens. Thinking
+and output accounting are provider-dependent. More output capacity can increase
+cost; monitor actual usage and finish diagnostics. No raw reasoning is requested
+or persisted by these settings.