Post-#259 cleanup for ContextResolver paths, Views, docs, and tests

[blindzero]

Problem Statement

PR #259 introduced the new ContextResolver architecture based on provider/auth-scoped source-of-truth paths, deterministic Views, and the execution-time Request.Context.Current alias.

This resolved the architectural direction, but follow-up cleanup is still needed to make the repository fully consistent.

At the moment, there is still a risk that some documentation, examples, troubleshooting guidance, comments, or tests may reflect older assumptions from the superseded flattening approach that was explored in PR #258. In particular, profile attribute access must be documented and tested consistently so workflow authors do not infer unsupported paths from outdated examples.

Without this cleanup, users may:

• use legacy or incorrect path assumptions,
• misunderstand the difference between scoped source-of-truth data and convenience Views,
• misdiagnose condition/template failures when inspecting resolver output.

Proposed Solution

Perform a focused post-#259 consistency pass covering documentation, examples, troubleshooting, and tests.

Scope:

1. Documentation consistency review

   • Review all ContextResolver-related docs and references.
   • Remove or correct any stale wording that implies the old flattening model.
   • Ensure the documentation consistently distinguishes:
     • source of truth:
       Request.Context.Providers.<ProviderAlias>.<AuthSessionKey>...
     • deterministic Views:
       Request.Context.Views...
     • execution-time alias:
       Request.Context.Current...

2. Correct profile attribute consumption examples

   • Review all examples using identity profile values.
   • Ensure examples use the actually supported path shape.
   • Explicitly document that workflow authors must not assume that convenience Views are raw mirrors of one scoped resolver output.

3. Troubleshooting improvements

   • Add a focused troubleshooting section for debugging ContextResolver output.
   • Document the recommended inspection/debugging approach, including:
     • dumping relevant context fragments with ConvertTo-Json,
     • checking scoped provider/auth paths first,
     • then checking the derived View,
     • understanding deterministic ordering / effective last-writer-wins selection for profile Views.
   • Explain why a View may differ from one specific scoped source path.

4. Test coverage review

   • Review existing tests for stale flattening expectations.
   • Add/adjust tests that verify:
     • supported profile attribute access paths,
     • deterministic View behavior,
     • examples/fixtures match the documented model,
     • no regressions around template substitution and condition-path validation.

5. Example workflow review

   • Recheck shipped examples for consistency with the post-ContextResolvers: Provider/Auth-scoped namespace, deterministic Views, Current alias #259 architecture.
   • Ensure examples demonstrate the intended authoring model clearly and unambiguously.

Alternatives Considered

1. Reopen or continue PR Remove attribute flattening to align with scoped ContextResolver model (breaking change) #258

   • Rejected because Remove attribute flattening to align with scoped ContextResolver model (breaking change) #258 was based on the earlier flattening approach and is no longer the desired architectural direction after ContextResolvers: Provider/Auth-scoped namespace, deterministic Views, Current alias #259.

2. Continue tracking this under bug ContextResolver Identity.Read values not working in EnsureOutOfOffice template substitution #254

   • Rejected because ContextResolver Identity.Read values not working in EnsureOutOfOffice template substitution #254 described one concrete failing path, while the remaining work is now broader consistency/documentation/test follow-up after the architectural redesign already merged in ContextResolvers: Provider/Auth-scoped namespace, deterministic Views, Current alias #259.

3. Do nothing

   • Rejected because stale examples or mixed guidance would continue to create author confusion and increase the risk of future regressions.

Impact

• Does this affect existing workflows?

  • It should not introduce a new behavioral change.
  • The main purpose is to ensure docs, examples, and tests reflect the already-merged ContextResolvers: Provider/Auth-scoped namespace, deterministic Views, Current alias #259 behavior correctly and consistently.

• Any backward compatibility concerns?

  • No new backward compatibility layer should be introduced.
  • The cleanup should follow the current post-ContextResolvers: Provider/Auth-scoped namespace, deterministic Views, Current alias #259 model consistently and remove ambiguity rather than preserve superseded path assumptions.

Additional Context

Step-0 guidance / acceptance focus:

• First validate the current repository state and identify every remaining place that still suggests or tests the superseded flattening model.
• Treat PR ContextResolvers: Provider/Auth-scoped namespace, deterministic Views, Current alias #259 as the architectural source of truth.
• Prefer root-cause consistency fixes over local wording-only patches.
• Update documentation, examples, inline comments, and tests together so the repository stays aligned.
• Include explicit troubleshooting guidance for inspecting resolver output and Views with ConvertTo-Json.
• Verify all changed examples and fixtures against the actual runtime/test behavior before finalizing.