PRD-439: Restructure and update NetBox Assurance documentation for Enterprise launch and Cloud availability

.gitignore

@@ -1,3 +1,4 @@
 docs/images/.DS_Store
 .DS_Store
-venv/
+venv/
+scratch

docs/netbox-assurance/index.md

@@ -1,28 +1,42 @@
-<span class="pill pill-cloud">NetBox Cloud</span>
-<span class="pill pill-enterprise">NetBox Enterprise</span>
+<span class="pill pill-enterprise">Enterprise</span>
 
-!!! info "*Coming early 2025*"
-    Be among the first to experience **NetBox Assurance**. [Sign up](https://netboxlabs.com/netbox-assurance/) to be notified when we launch.
+!!! note "NetBox Cloud Support"
+    NetBox Cloud support coming early July 2025.
 
-NetBox Assurance empowers organizations to continuously detect and address network drift by identifying deviations between the intended state in NetBox and the actual state of the network. It extends NetBox with automated deviation detection and corrective actions, helping teams maintain a consistent and reliable network infrastructure.
+NetBox Assurance allows you to control which data goes into NetBox by detecting and managing "operational drift"—the difference between your intended network state documented in NetBox and the actual operational state of your network infrastructure.
 
 ## Key Features
-- **Deviation Detection**: Identify configuration drift between NetBox and the network.
-- **Efficient Remediation**: Correct detected deviations through guided workflows.
-- **Seamless Integration**: Enhance NetBox with continuous network validation and state synchronization.
-- **Detailed Reports**: Generate actionable reports highlighting network consistency and detected deviations.
+- **Operational Drift Detection**: Identify differences between NetBox's intended state and actual network state
+- **Data Ingestion Control**: Review and approve data before it enters NetBox, maintaining data quality
+- **Seamless Integration**: Works with NetBox Discovery and supports custom integrations via the Diode SDK
+- **Change Set Management**: Review proposed updates and apply them to NetBox branches or ignore as needed
+- **Audit Trail**: Track all changes and decisions for compliance and operational history
 
 ## How It Works
-NetBox Assurance continuously compares the documented or intended network state stored in NetBox with the observed network state being provided by NetBox Discovery and other network data sources. When deviations are detected, workflows allow effecient remediation of deviations by updating NetBox or by taking corrective actions on the network.
+NetBox Assurance follows a structured four-step workflow:
+
+1. **Data Ingestion**: Network information flows in from NetBox Discovery, direct device interrogation, or other sources via the Diode SDK
+2. **Analysis & Comparison**: Ingested data is analyzed against existing NetBox records to identify operational drift
+3. **Deviation Review**: Review detected deviations and examine proposed change sets
+4. **Action & Resolution**: Apply changes to NetBox, recalculate drift, or ignore deviations as needed
+
+![NetBox Assurance Main Interface](images/assurance-main-page.png)
 
 ## Use Cases
-- **Network Drift Detection**: Ensure network configurations remain consistent with the source of truth.
-- **Compliance Audits**: Support compliance efforts by detecting unauthorized changes.
-- **Incident Prevention**: Identify and address deviations before they cause major disruptions.
+- **Day 1 - Initial NetBox Population**: Control data quality while rapidly populating NetBox with discovery data
+- **Day 1.5 - Improving Network Maturity**: Maintain operations while gradually improving documentation and automation processes  
+- **Day 2 - Operational Excellence**: Proactively detect and resolve operational drift to maintain network reliability
+
+## Getting Started
+
+1. **[Quickstart Guide](quickstart-guide.md)**: Get up and running quickly with NetBox Assurance
+2. **[Assurance Workflows](workflows/index.md)**: Configure drift detection and review processes
+3. **[Data Ingestion](monitoring/index.md)**: Set up data sources from NetBox Discovery and other systems
 
 ## Support and Resources
-- **Documentation**: Until NetBox Assurance is officially released, please refer to the [Diode](../netbox-extensions/diode/index.md) project documentation.
-- **Community Support**: Connect with the community on [Slack](https://netdev.chat/) in the `#netbox` channel.
+- **Community Support**: Connect with the community on [Slack](https://netdev.chat/) in the `#netbox` channel
+- **Documentation**: Additional resources and integration guides available in related sections
+- **GitHub Repository**: Find NetBox Discovery integration [here](https://github.com/netboxlabs/orb-agent)
 
 ---
-With **NetBox Assurance**, teams can detect, report, and resolve network deviations in real time, ensuring a consistent and reliable network environment through continuous validation and corrective actions.
+By leveraging **NetBox Assurance**, organizations can maintain accurate network documentation, reduce operational risk, and build confidence in their network automation initiatives through continuous validation and drift detection.

docs/netbox-assurance/monitoring/index.md

@@ -0,0 +1,92 @@
+<span class="pill pill-enterprise">Enterprise</span>
+
+# Data Ingestion and Analysis
+
+!!! note "NetBox Cloud Support"
+    NetBox Cloud support coming early July 2025.
+
+NetBox Assurance ingests network data from multiple sources and analyzes it against your NetBox documentation to identify operational drift. This process ensures your network documentation stays accurate and up-to-date.
+
+## Data Sources
+
+### NetBox Discovery Integration
+The primary source for automated network data collection:
+
+- **Network Discovery**: Automated discovery of network devices and topology
+- **Device Discovery**: Detailed device inventory and configuration collection
+- **Controller Integrations**: VMware vCenter, Cisco Catalyst Center, Juniper Mist, Microsoft DHCP, AWS VPC IPAM
+
+![Diode Configuration](../images/diode_settings_endpoint.png)
+
+### Diode SDK Integration
+Public API for custom data sources and integrations:
+
+- **Python and Golang SDKs**: Development kits for building custom integrations
+- **Monitoring Systems**: Prometheus, Grafana, DataDog, Splunk
+- **Inventory Systems**: CMDBs, spreadsheets, asset management systems
+- **Automation Tools**: Ansible, Terraform, custom scripts
+
+![Diode Credentials](../images/diode_credentials.png)
+
+### Direct API Access
+Send data directly to NetBox Assurance:
+- **REST API**: Standard HTTP-based data submission
+- **Bulk Operations**: Efficient handling of large data sets
+- **Real-time Updates**: Immediate processing of network changes
+- **Idempotent Operations**: Safe to retry without duplicating data
+
+## Analysis Process
+
+### Operational Drift Detection
+NetBox Assurance compares ingested data against existing NetBox records to identify:
+
+- **Missing Objects**: Network elements discovered but not documented in NetBox
+- **Obsolete Objects**: NetBox entries that no longer exist in the actual network
+- **Configuration Drift**: Differences in device attributes, IP addresses, or relationships
+- **Topology Changes**: New connections or removed links between devices
+
+### Data Quality Control
+Before data enters NetBox, Assurance provides:
+
+- **Change Preview**: See exactly what would be modified in NetBox
+- **Impact Analysis**: Understand the scope of proposed changes
+- **Conflict Resolution**: Handle overlapping or contradictory data
+- **Validation Rules**: Ensure data meets organizational standards
+
+![Deviation Review](../images/assurance-detail.png)
+
+## Integration Patterns
+
+### Continuous Monitoring
+Real-time observation of network state:
+- **Event-driven Updates**: Process changes as they occur
+- **Low-latency Detection**: Immediate identification of drift
+- **Critical Infrastructure Focus**: Priority monitoring for essential systems
+
+### Scheduled Collection
+Periodic comprehensive data gathering:
+- **Daily Discovery Runs**: Regular network scans
+- **Weekly Compliance Audits**: Systematic validation of network state
+- **Monthly Trend Analysis**: Long-term drift pattern identification
+
+### Hybrid Approach
+Combination of real-time and scheduled monitoring:
+- **Critical Systems**: Continuous monitoring for core infrastructure
+- **Standard Systems**: Scheduled collection for routine equipment
+- **Flexible Policies**: Different monitoring strategies per device type
+
+## Getting Started
+
+1. **Configure NetBox Discovery**: Set up automated network and device discovery
+2. **Enable Diode Integration**: Connect monitoring systems and data sources
+3. **Define Data Sources**: Specify which systems should send data to Assurance
+4. **Set Collection Schedules**: Determine how frequently to gather network data
+5. **Review Initial Results**: Examine first deviations and tune detection sensitivity
+
+## Best Practices
+
+- **Start with Discovery**: Use NetBox Discovery as your primary data source
+- **Gradual Expansion**: Add custom integrations incrementally
+- **Data Validation**: Verify data quality before large-scale ingestion
+- **Monitor Performance**: Track ingestion rates and processing times
+- **Document Sources**: Maintain clear records of all data integration points 

docs/netbox-assurance/quickstart-guide.md

@@ -0,0 +1,63 @@
+<span class="pill pill-enterprise">Enterprise</span>
+
+# NetBox Assurance Quickstart Guide
+
+!!! note "NetBox Cloud Support"
+    NetBox Cloud support coming early July 2025.
+
+This quickstart guide will help you get NetBox Assurance up and running to detect and manage operational drift between your intended network state in NetBox and the actual state of your network infrastructure.
+
+## Prerequisites
+
+- NetBox Enterprise installation with Assurance enabled
+- Network data sources configured (NetBox Discovery recommended)
+- Administrative access to NetBox Enterprise
+- Network devices accessible for data collection
+
+## Installation and Setup
+
+### Step 1: Enable NetBox Assurance
+
+During NetBox Enterprise installation, ensure NetBox Assurance is selected in the configuration screen:
+
+![NetBox Enterprise Installation](images/assurance-console-install.png)
+
+### Step 2: Access NetBox Assurance
+
+Once installed, NetBox Assurance appears in your NetBox navigation sidebar:
+
+![NetBox Assurance Interface](images/assurance-main-page.png)
+
+### Step 3: Configure Data Sources
+
+Set up data ingestion from one or more sources:
+
+- **NetBox Discovery**: Leverage existing network and device discovery data
+- **Diode SDK**: Configure custom integrations with monitoring systems, CMDBs, or other data sources
+- **Direct API**: Send data directly from scripts or automation tools
+
+### Step 4: Review Your First Deviations
+
+Once data flows in, Assurance will detect operational drift and present deviations for review:
+
+![Deviations Dashboard](images/Assurance_all_deviations.png)
+
+### Step 5: Take Action
+
+For each deviation, you can:
+- **Apply**: Update NetBox with the discovered network state
+- **Ignore**: Mark as acceptable deviation
+- **Recalculate**: Refresh the comparison after making changes
+
+![Apply Changes](images/assurance-detail-apply-confirm.png)
+
+## Next Steps
+
+- **[Configure Workflows](workflows/index.md)**: Set up automated drift detection rules
+- **[Data Ingestion Setup](monitoring/index.md)**: Configure additional data sources
+- **[Workflow Configuration](workflows/configuration.md)**: Customize detection and review processes
+
+## Getting Help
+
+- **Community Support**: Join the [NetBox Slack](https://netdev.chat/) `#netbox` channel
+- **Documentation**: Explore the detailed workflow and configuration guides 

docs/netbox-assurance/workflows/configuration.md

@@ -0,0 +1,105 @@
+<span class="pill pill-enterprise">Enterprise</span>
+
+# Workflow Configuration
+
+!!! note "NetBox Cloud Support"
+    NetBox Cloud support coming early July 2025.
+
+This page covers how to configure NetBox Assurance workflows to manage data ingestion and detect operational drift from the intended state in NetBox.
+
+## Configuration Overview
+
+NetBox Assurance workflows are configured through the NetBox interface and consist of:
+
+- **Monitoring Targets**: Devices, services, or network segments to monitor
+- **Detection Rules**: Criteria that define what constitutes a deviation
+- **Actions**: Responses to execute when deviations are detected
+- **Schedules**: When and how often to run the workflow
+
+## Basic Workflow Configuration
+
+### 1. Define Monitoring Targets
+
+Specify which network elements to monitor:
+
+```yaml
+targets:
+  - device_role: "router"
+    site: "datacenter-01"
+  - device_type: "cisco-catalyst-9300"
+    tenant: "production"
+```
+
+### 2. Set Detection Rules
+
+Configure the conditions that trigger deviation alerts:
+
+```yaml
+rules:
+  - name: "Configuration Drift"
+    type: "config_comparison"
+    threshold: "any_change"
+  - name: "Interface State"
+    type: "operational_state"
+    expected: "up"
+```
+
+### 3. Configure Actions
+
+Define what happens when deviations are detected:
+
+```yaml
+actions:
+  - type: "alert"
+    severity: "warning"
+    recipients: ["[email protected]"]
+  - type: "create_ticket"
+    system: "servicenow"
+    priority: "medium"
+```
+
+## Advanced Configuration
+
+### Custom Validation Rules
+
+Create custom rules for organization-specific requirements:
+
+```yaml
+custom_rules:
+  - name: "VLAN Consistency"
+    description: "Ensure VLANs match NetBox configuration"
+    script: |
+      # Custom validation logic
+      if device.vlans != netbox.vlans:
+          return deviation_found("VLAN mismatch detected")
+```
+
+### Remediation Workflows
+
+Configure automatic remediation for common issues:
+
+```yaml
+remediation:
+  - condition: "interface_down"
+    action: "restart_interface"
+    approval_required: false
+  - condition: "config_drift"
+    action: "restore_config"
+    approval_required: true
+```
+
+## Best Practices
+
+- Start with read-only monitoring before enabling remediation
+- Test workflows in non-production environments first
+- Use appropriate notification channels for different severity levels
+- Regularly review and update detection rules
+- Monitor workflow performance and adjust schedules as needed
+
+## Troubleshooting
+
+Common configuration issues and solutions:
+
+- **Workflow not triggering**: Check monitoring target configuration and device accessibility
+- **False positives**: Refine detection rules to reduce noise
+- **Performance issues**: Adjust monitoring frequency and target scope