From 4f554b902a14830d50298c00095aa7c6c6a5771d Mon Sep 17 00:00:00 2001 From: Charles Cunningham Date: Fri, 13 Mar 2026 03:26:32 -0700 Subject: [PATCH] Clarify contextual user fragment registry docs Document the contextual user registry with the same level of guidance as the developer registry, including detection-only fragments versus turn-state diff fragments. Co-authored-by: Codex --- codex-rs/core/src/model_visible_context.rs | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/codex-rs/core/src/model_visible_context.rs b/codex-rs/core/src/model_visible_context.rs index 2080b90d38..58dffd50ae 100644 --- a/codex-rs/core/src/model_visible_context.rs +++ b/codex-rs/core/src/model_visible_context.rs @@ -259,9 +259,21 @@ where /// Canonical contextual-user fragment registry. /// -/// Add new contextual-user fragment types here so injected context is not -/// mistaken for real user intent during event mapping/truncation, and to wire -/// turn-state contextual-user diff fragments in one place. +/// Add new contextual-user fragments by: +/// 1. Defining a typed fragment struct. +/// 2. Implementing `ModelVisibleContextFragment` with +/// `Role = ContextualUserContextRole`. +/// 3. Implementing contextual-user detection via +/// `TaggedContextualUserFragment` or `ContextualUserFragmentDetector`. +/// 4. If the fragment is derived from turn state, implementing +/// `TurnContextDiffFragment::build` and registering it with +/// `Some(build_contextual_user_turn_state_fragment::)`. +/// 5. Otherwise registering it with `None` for diffing so it still participates +/// in contextual-user history parsing. +/// +/// Register new fragment types here so injected context is not mistaken for +/// real user intent during event mapping/truncation, and to wire turn-state +/// contextual-user diff fragments in one place. const REGISTERED_CONTEXTUAL_USER_FRAGMENTS: &[ContextualUserFragmentRegistration] = &[ ContextualUserFragmentRegistration::new( detect_contextual_user_fragment::,