docs: add flexible field support documentation

- Create docs/flexible-field-support.md with comprehensive guide
- Document usage patterns for nova-flexible-content integration
- Explain context-aware attribute resolution mechanism
- Document supported attribute format patterns
- Include limitations and troubleshooting sections

Author: iamgerwin

docs/flexible-field-support.md

@@ -0,0 +1,159 @@
+# Flexible Field Support
+
+This document describes how `NovaDependencyContainer` works with [whitecube/nova-flexible-content](https://github.com/whitecube/nova-flexible-content) Flexible fields.
+
+## Overview
+
+Starting from version 1.0.5, `NovaDependencyContainer` supports conditional field visibility inside Flexible field layouts. This enables dynamic form behavior within repeatable content blocks.
+
+## The Problem
+
+When fields are placed inside a Flexible layout, their attribute names are automatically prefixed by the Flexible field component. For example:
+
+- A field named `type` inside a Flexible layout becomes `overlay_items__0__type`
+- The index (`0`, `1`, `2`, etc.) changes based on the layout position
+
+This prefixing caused the original dependency detection to fail because it looked for exact attribute matches.
+
+## The Solution
+
+The package now implements **context-aware dependency resolution** that:
+
+1. Detects when a field is inside a Flexible layout context
+2. Automatically resolves relative field names to their prefixed equivalents
+3. Supports multiple Flexible attribute formats (double underscore and bracket notation)
+4. Falls back to suffix matching for edge cases
+
+## Usage
+
+Use `NovaDependencyContainer` inside Flexible layouts exactly as you would elsewhere:
+
+```php
+use Iamgerwin\NovaDependencyContainer\NovaDependencyContainer;
+use Whitecube\NovaFlexibleContent\Flexible;
+use Laravel\Nova\Fields\Select;
+use Laravel\Nova\Fields\Text;
+
+Flexible::make('Overlay Items')
+    ->addLayout('Overlay Item', 'overlay_item', [
+        Select::make('Type')
+            ->options([
+                'Default' => 'Default',
+                'Location' => 'Location',
+                'Contact Us' => 'Contact Us',
+            ]),
+
+        NovaDependencyContainer::make([
+            Text::make('Recipient Email', 'recipient_email')
+                ->rules('nullable', 'email', 'max:255'),
+        ])->dependsOn('type', 'Contact Us'),
+
+        NovaDependencyContainer::make([
+            Text::make('Location Name', 'location_name'),
+            Text::make('Address', 'address'),
+        ])->dependsOn('type', 'Location'),
+    ]),
+```
+
+## How It Works
+
+### Attribute Resolution
+
+When you specify `dependsOn('type', 'Contact Us')`, the package:
+
+1. First attempts an exact match for `type`
+2. If not found, detects the Flexible context prefix from sibling fields
+3. Resolves to the prefixed attribute (e.g., `overlay_items__0__type`)
+4. Checks multiple format variations for compatibility
+
+### Supported Attribute Formats
+
+The package recognizes these Flexible field attribute patterns:
+
+| Format | Example |
+|--------|---------|
+| Double underscore | `overlay_items__0__type` |
+| Bracket notation | `overlay_items[0][type]` |
+| Single underscore | `overlay_items_0_type` |
+
+### Event Handling
+
+When a field value changes inside a Flexible layout:
+
+1. The change event includes the full prefixed attribute
+2. The package extracts the base attribute name
+3. Both the full and base attribute values are cached
+4. Dependencies are re-evaluated against all matching fields
+
+## Multiple Flexible Groups
+
+Dependencies work correctly across multiple instances of the same layout. Each layout group maintains its own context, so changing `type` in one Overlay Item only affects the dependent fields in that same group.
+
+```php
+// Layout instance 0: type = 'Contact Us' -> shows recipient_email
+// Layout instance 1: type = 'Location' -> shows location_name, address
+// Layout instance 2: type = 'Default' -> hides all dependent fields
+```
+
+## Limitations
+
+### Cross-Group Dependencies
+
+Currently, dependencies are resolved within the same Flexible group context. Cross-group dependencies (e.g., a field in group 0 depending on a field in group 1) are not supported.
+
+### Deeply Nested Flexible Fields
+
+The package supports one level of Flexible field nesting. Deeply nested Flexible fields (Flexible inside Flexible) may not resolve correctly.
+
+### Detail View
+
+Flexible field support works best on form views (create/edit). Detail view support is included but may have limitations depending on how the Flexible content renders field data.
+
+## Troubleshooting
+
+### Dependency Not Triggering
+
+If a dependency isn't working inside a Flexible layout:
+
+1. **Check the field attribute name**: Ensure you're using the simple attribute name (e.g., `type`) not the prefixed version
+2. **Verify the field exists**: The dependent field must be in the same Flexible layout group
+3. **Check the console**: Browser dev tools may show helpful debugging information
+
+### Field Visibility Stuck
+
+If a field remains hidden when it should be visible:
+
+1. Try selecting a different option and then back to the triggering value
+2. Ensure the comparison value matches exactly (including case sensitivity)
+
+## Technical Details
+
+### Context Detection
+
+The Flexible context is detected by examining:
+
+1. The container's own `attribute` property
+2. Sibling field `attribute` properties
+3. Parent component structure
+
+### Regex Patterns Used
+
+```javascript
+// Double underscore format
+/^(.+__\d+__)/
+
+// Bracket format
+/^(.+\[\d+\]\[)/
+
+// Base attribute extraction (double underscore)
+/^.+__\d+__(.+)$/
+
+// Base attribute extraction (bracket)
+/^.+\[\d+\]\[(.+)\]$/
+```
+
+## Version History
+
+- **1.0.5**: Added Flexible field support (this feature)
+- **1.0.4**: Nova 4.35.x compatibility fixes
+- **1.0.0**: Initial release