@@ -1,6 +1,17 @@
 ## [Unreleased]
 
 ### Added
+
+- **📚 Documentation: Comprehensive Tutorial & Integration Improvements**
+  - **Strands Integration**: Removed incorrect `set_tracer_provider()` requirement - SDK auto-handles provider setup
+  - **Strands Integration**: Added clear integration/user code distinction with comment separators
+  - **Tutorial 02**: Added explicit tracer→instrumentor initialization order callout
+  - **Tutorial 02**: Added non-instrumentor pattern section (using `@trace` decorator directly)
+  - **Tutorial 03**: Added comprehensive `enrich_session()` vs `enrich_span()` guide with decision matrix
+  - **Tutorial 03**: Added global vs instance method callout for `enrich_span()` patterns
+  - **Tutorial 06**: Added middleware alternative pattern for distributed tracing (without `context.attach()`)
+  - **Advanced Tracing**: Added session-level vs span-level enrichment documentation with complete examples
+
 - **📚 Documentation: Tracer Initialization Patterns Guide**
   - New comprehensive guide: "Where Should I Initialize the Tracer?"
   - Covers 5 scenarios: local dev, evaluate(), serverless, long-running server, testing
@@ -11,13 +22,26 @@
   - Location: `docs/how-to/deployment/tracer-initialization-patterns.rst`
 
 ### Fixed
+
+- **📚 Documentation: Fixed Docstring Formatting Issues**
+  - Fixed numerous extra newlines in tutorial docstrings (Tutorials 01, 03, 05)
+  - Corrected dashboard URL to `https://app.honeyhive.ai/evaluate` (Tutorial 05)
+  - Fixed broken cross-references after removing redundant advanced-setup tutorial
+  - Updated reference docs link in Tutorial 02 to point to correct API decorator documentation
+
 - **📚 README: Corrected Import Path for PyPI Display**
   - Fixed incorrect import `from honeyhive.tracer.decorators import trace` → `from honeyhive import trace`
   - Fixed documentation URL from `docs.honeyhive.ai` to `honeyhiveai.github.io/python-sdk`
   - Simplified Quick Start example (removed redundant comments)
   - Ensures PyPI package page shows correct usage examples
 
 ### Changed
+
+- **📚 Documentation: Content Improvements**
+  - Documented tracer instance parameter for evaluation functions (Tutorial 05)
+  - Removed redundant Timing and Error Enrichment sections from Tutorial 03 (now shown in Complete Example)
+  - Deleted 2,088-line advanced-setup.rst tutorial (content was redundant with advanced-configuration.rst)
+
 - **Version 1.0.0-rc3**: Bumped from 0.1.0-rc3 to reflect stable API
 - **📚 Documentation: Strands Integration - Instance Method Pattern**
   - Updated all `enrich_span()` usage to use instance method pattern (`tracer.enrich_span()`)
 
@@ -1313,6 +1313,6 @@ See Also
 
 - :doc:`performance-testing` - Performance testing strategies
 - :doc:`ci-cd-integration` - CI/CD integration patterns  
-- :doc:`../../tutorials/advanced-setup` - Advanced Lambda configuration
+- :doc:`../../tutorials/advanced-configuration` - Advanced Lambda configuration
 - :doc:`../../how-to/deployment/production` - Production deployment guide
 - :doc:`../../reference/configuration/environment-vars` - Environment configuration
@@ -1258,5 +1258,5 @@ See Also
 - :doc:`lambda-testing` - AWS Lambda performance testing
 - :doc:`integration-testing` - Integration performance testing
 - :doc:`ci-cd-integration` - Automated performance testing
-- :doc:`../../tutorials/advanced-setup` - Performance optimization configuration
+- :doc:`../../tutorials/advanced-configuration` - Performance optimization configuration
 - :doc:`../../reference/configuration/environment-vars` - Performance-related settings
@@ -608,4 +608,4 @@ See Also
 - :doc:`overview` - Architecture overview
 - :doc:`byoi-design` - BYOI design explanation
 - :doc:`overview` - Architecture overview
-- :doc:`../../tutorials/advanced-setup` - Advanced setup tutorial
+- :doc:`../../tutorials/advanced-configuration` - Advanced setup tutorial
@@ -7,6 +7,129 @@ Span Enrichment Patterns
 
 This guide covers advanced enrichment techniques beyond the basics. For an introduction, see :doc:`/tutorials/03-enable-span-enrichment`.
 
+Session-Level vs Span-Level Enrichment
+---------------------------------------
+
+HoneyHive provides two enrichment scopes: **session-level** and **span-level**.
+
+**``enrich_session()`` - Apply metadata to all spans in a session:**
+
+.. code-block:: python
+
+   from honeyhive import HoneyHiveTracer
+   
+   tracer = HoneyHiveTracer.init(project="my-app")
+   
+   # Apply to ALL spans in this session
+   tracer.enrich_session({
+       "user_id": "user_456",
+       "user_tier": "enterprise",
+       "environment": "production",
+       "deployment_region": "us-east-1"
+   })
+   
+   # All subsequent operations inherit this metadata
+   response1 = call_llm(...)
+   response2 = call_llm(...)
+   response3 = call_llm(...)
+   # All 3 traces will have user_id, user_tier, environment, deployment_region
+
+**Use ``enrich_session()`` for:**
+
+- ✅ User identification (user_id, email, tier)
+- ✅ Session context (session_type, workflow_name)
+- ✅ Environment info (environment, region, version)
+- ✅ Business context (customer_id, account_type, plan)
+- ✅ Any metadata that applies to the entire user session
+
+**``enrich_span()`` - Apply metadata to a single span:**
+
+.. code-block:: python
+
+   from honeyhive import enrich_span
+   
+   def process_query(query: str, use_cache: bool):
+       # Apply to THIS specific span only
+       enrich_span({
+           "query_length": len(query),
+           "cache_enabled": use_cache,
+           "model": "gpt-4",
+           "temperature": 0.7
+       })
+       
+       return call_llm(query)
+
+**Use ``enrich_span()`` for:**
+
+- ✅ Per-call parameters (model, temperature, max_tokens)
+- ✅ Call-specific metrics (input_length, cache_hit, latency)
+- ✅ Dynamic metadata (intent_classification, confidence_score)
+- ✅ Error details (error_type, retry_count)
+- ✅ Any metadata that varies per LLM call
+
+**Example combining both:**
+
+.. code-block:: python
+
+   from honeyhive import HoneyHiveTracer
+   
+   # Session-level: Set once for the entire user session
+   tracer = HoneyHiveTracer.init(
+       project="customer-support",
+       session_name="support-session-789"
+   )
+   
+   tracer.enrich_session({
+       "user_id": "user_456",
+       "support_tier": "premium",
+       "issue_category": "billing"
+   })
+   
+   # Span-level: Varies per call
+   def handle_query(query: str):
+       intent = classify_intent(query)
+       
+       tracer.enrich_span({
+           "query_intent": intent,
+           "query_length": len(query),
+           "model": "gpt-4" if intent == "complex" else "gpt-3.5-turbo"
+       })
+       
+       return generate_response(query)
+   
+   # Each call has both session + span metadata
+   handle_query("How do I change my billing address?")
+   handle_query("What's my current balance?")
+   handle_query("Can I upgrade my plan?")
+
+**Decision Matrix:**
+
++------------------------------+-------------------------+-------------------------+
+| **Metadata Type**            | **Scope**               | **Method**              |
++==============================+=========================+=========================+
+| User ID, email               | Session (constant)      | ``enrich_session()``    |
++------------------------------+-------------------------+-------------------------+
+| Model name, temperature      | Span (varies)           | ``enrich_span()``       |
++------------------------------+-------------------------+-------------------------+
+| Environment (prod/dev)       | Session (constant)      | ``enrich_session()``    |
++------------------------------+-------------------------+-------------------------+
+| Cache hit/miss               | Span (per-call)         | ``enrich_span()``       |
++------------------------------+-------------------------+-------------------------+
+| Customer tier                | Session (constant)      | ``enrich_session()``    |
++------------------------------+-------------------------+-------------------------+
+| Prompt token count           | Span (per-call)         | ``enrich_span()``       |
++------------------------------+-------------------------+-------------------------+
+| Deployment region            | Session (constant)      | ``enrich_session()``    |
++------------------------------+-------------------------+-------------------------+
+| Error type/message           | Span (when it occurs)   | ``enrich_span()``       |
++------------------------------+-------------------------+-------------------------+
+
+.. tip::
+   **Rule of Thumb:**
+   
+   If the metadata is the same for all LLM calls in a user session, use ``enrich_session()``.
+   If it changes per call, use ``enrich_span()``.
+
 Understanding Enrichment Interfaces
 -----------------------------------
 
 
@@ -24,13 +24,14 @@ AWS Strands is an AI agent framework that:
 Integration Approach
 ~~~~~~~~~~~~~~~~~~~~
 
-HoneyHive integrates with AWS Strands using the **OpenTelemetry TracerProvider pattern**.
+HoneyHive integrates with AWS Strands using **automatic OpenTelemetry provider setup**.
 
 **Key Difference from Other Integrations:**
 
 Unlike OpenAI or Anthropic (which require instrumentors like OpenInference or Traceloop), **AWS Strands has built-in OpenTelemetry tracing**. This means:
 
 - ✅ **NO instrumentor needed** - Strands instruments its own LLM calls
+- ✅ **NO manual provider setup** - ``HoneyHiveTracer.init()`` handles it automatically
 - ✅ **Built-in GenAI conventions** - All model calls automatically traced
 - ✅ **Don't use OpenInference/Traceloop** - Would create duplicate spans
 - ✅ **Zero modifications to Strands code** - Works with Strands as-is
@@ -41,10 +42,22 @@ Unlike OpenAI or Anthropic (which require instrumentors like OpenInference or Tr
 
 **How It Works:**
 
-1. HoneyHive provides a TracerProvider
-2. Set it as the global OpenTelemetry provider
-3. Strands automatically uses it for all its built-in tracing
-4. All LLM calls, agent actions, and tool executions are traced
+1. Call ``HoneyHiveTracer.init()`` - automatically sets up global TracerProvider
+2. Strands automatically uses it for all its built-in tracing
+3. All LLM calls, agent actions, and tool executions are traced
+
+Complete Example
+~~~~~~~~~~~~~~~~
+
+**See the full code:** `strands_integration.py <https://github.com/honeyhiveai/python-sdk/blob/main/examples/integrations/strands_integration.py>`_
+
+A comprehensive working example is available in the repository at ``examples/integrations/strands_integration.py``:
+
+- ✅ All 8 integration patterns shown below
+- ✅ Basic agent invocation, tool execution, streaming responses
+- ✅ Custom trace attributes, structured outputs with Pydantic
+- ✅ Swarm multi-agent collaboration, graph workflows with parallel processing
+- ✅ Copy-paste ready code for quick start
 
 What Gets Traced
 ~~~~~~~~~~~~~~~~
@@ -138,22 +151,22 @@ Minimal Setup (3 Lines of Code)
 
 .. code-block:: python
 
+   # ============= HONEYHIVE INTEGRATION =============
    from honeyhive import HoneyHiveTracer
-   from strands import Agent
-   from strands.models import BedrockModel
-   from opentelemetry import trace as trace_api
    import os
    
-   # 1. Initialize HoneyHive tracer
+   # Initialize HoneyHive tracer - automatic global provider setup
    tracer = HoneyHiveTracer.init(
        api_key=os.getenv("HH_API_KEY"),
        project="strands-demo",
    )
+   # ==================================================
    
-   # 2. Set as global TracerProvider (BEFORE creating agents)
-   trace_api.set_tracer_provider(tracer.provider)
+   # ============= YOUR STRANDS CODE ==================
+   from strands import Agent
+   from strands.models import BedrockModel
    
-   # 3. Use Strands normally - tracing is automatic!
+   # Use Strands normally - tracing is automatic!
    agent = Agent(
        name="BasicAgent",
        model=BedrockModel(model_id="anthropic.claude-haiku-4-5-20251001-v1:0"),
@@ -162,29 +175,37 @@ Minimal Setup (3 Lines of Code)
    
    result = agent("What is 2+2?")
    print(result)  # "2+2 equals 4"
+   # ==================================================
 
 **That's it!** All agent activity is now automatically traced to HoneyHive.
 
+.. note::
+   **No Manual Provider Setup Required**
+   
+   Unlike some integrations, you don't need to manually call ``trace_api.set_tracer_provider()``. 
+   The SDK automatically handles OpenTelemetry provider setup during ``HoneyHiveTracer.init()``.
+   
+   AWS Strands has built-in OpenTelemetry support that works seamlessly with HoneyHive's automatic configuration.
+
 Basic Agent Example
 ~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: python
 
+   # ============= HONEYHIVE INTEGRATION =============
    from honeyhive import HoneyHiveTracer
-   from strands import Agent
-   from strands.models import BedrockModel
-   from opentelemetry import trace as trace_api
    import os
    
-   # Initialize HoneyHive
    tracer = HoneyHiveTracer.init(
        api_key=os.getenv("HH_API_KEY"),
        project="strands-agents",
        session_name="basic-agent-demo"
    )
+   # ==================================================
    
-   # Set as global provider
-   trace_api.set_tracer_provider(tracer.provider)
+   # ============= YOUR STRANDS CODE ==================
+   from strands import Agent
+   from strands.models import BedrockModel
    
    # Create agent
    agent = Agent(
@@ -724,13 +745,11 @@ This happens if you accidentally enable LLM instrumentors (OpenInference/Tracelo
    from openinference.instrumentation.openai import OpenAIInstrumentor
    OpenAIInstrumentor().instrument()  # Will create duplicate spans!
    
-   # ✅ DO THIS - Just use TracerProvider pattern
+   # ✅ DO THIS - Just initialize HoneyHive
    from honeyhive import HoneyHiveTracer
-   from opentelemetry import trace as trace_api
    
    tracer = HoneyHiveTracer.init(...)
-   trace_api.set_tracer_provider(tracer.provider)
-   # That's it - Strands handles the rest!
+   # That's it - automatic provider setup, Strands handles the rest!
 
 **Issue: "Unable to locate credentials"**
 
@@ -764,7 +783,7 @@ Use correct Bedrock model IDs (not OpenAI model names):
 
 1. Verify ``HH_API_KEY`` is set correctly
 2. Check project name matches your HoneyHive project
-3. Ensure ``trace_api.set_tracer_provider()`` is called BEFORE creating agents
+3. Ensure ``HoneyHiveTracer.init()`` is called BEFORE creating agents
 4. Look for error messages in console output
 
 Debugging Traces
@@ -804,20 +823,19 @@ Print session ID for manual verification:
 Best Practices
 --------------
 
-1. **Set TracerProvider Early**
+1. **Initialize Tracer Early**
 
-   Always call ``trace_api.set_tracer_provider()`` before creating agents:
+   Always call ``HoneyHiveTracer.init()`` before creating agents (automatic provider setup):
 
    .. code-block:: python
 
       # ✅ Correct order
-      tracer = HoneyHiveTracer.init(...)
-      trace_api.set_tracer_provider(tracer.provider)
+      tracer = HoneyHiveTracer.init(...)  # Automatic global provider setup
       agent = Agent(...)  # Now traced
       
       # ❌ Wrong order
       agent = Agent(...)  # Not traced
-      tracer = HoneyHiveTracer.init(...)
+      tracer = HoneyHiveTracer.init(...)  # Too late!
 
 2. **Don't Use LLM Instrumentors**
 
@@ -831,8 +849,7 @@ Best Practices
       
       # ✅ DO THIS - Strands instruments itself
       tracer = HoneyHiveTracer.init(...)
-      trace_api.set_tracer_provider(tracer.provider)
-      # Strands' built-in tracing handles everything
+      # Strands' built-in tracing handles everything (no manual provider setup needed)
 
 3. **Use Meaningful Agent Names**
 
@@ -894,21 +911,4 @@ Next Steps
 - :doc:`/reference/api/tracer` - Full tracer API reference
 - `AWS Strands Documentation <https://github.com/strands-agents/sdk-python>`_ - Learn more about Strands
 
-Complete Example
-----------------
-
-A comprehensive example is available in the repository:
-
-**`examples/integrations/strands_integration.py`** - Full integration demo with 8 test cases:
-
-- Basic agent invocation
-- Tool execution with calculator
-- Streaming responses
-- Custom trace attributes
-- Structured outputs with Pydantic
-- Swarm multi-agent collaboration
-- Graph workflows with parallel processing
-- All patterns shown in this guide
-
-View it on GitHub: `strands_integration.py <https://github.com/honeyhiveai/python-sdk/blob/main/examples/integrations/strands_integration.py>`_