diff --git a/includes/collector/class-prv-ai-visibility-collector.php b/includes/collector/class-prv-ai-visibility-collector.php
index cb4fbe3..79fee94 100644
--- a/includes/collector/class-prv-ai-visibility-collector.php
+++ b/includes/collector/class-prv-ai-visibility-collector.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * AI-visibility data collector for the PR Vision dashboard.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/collector/interface-prv-data-collector.php b/includes/collector/interface-prv-data-collector.php
index c77c647..02944ba 100644
--- a/includes/collector/interface-prv-data-collector.php
+++ b/includes/collector/interface-prv-data-collector.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Contract for all PR Vision data collectors.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-activator.php b/includes/core/class-prv-activator.php
index 3fe40cd..6071a95 100644
--- a/includes/core/class-prv-activator.php
+++ b/includes/core/class-prv-activator.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Plugin activation handler.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-admin-page.php b/includes/core/class-prv-admin-page.php
index 5f7afb9..f13e6db 100644
--- a/includes/core/class-prv-admin-page.php
+++ b/includes/core/class-prv-admin-page.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * PR Vision top-level admin page.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-autoloader.php b/includes/core/class-prv-autoloader.php
index 62ea42b..110846e 100644
--- a/includes/core/class-prv-autoloader.php
+++ b/includes/core/class-prv-autoloader.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Class and interface autoloader for the PR Vision plugin.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-collector-registry.php b/includes/core/class-prv-collector-registry.php
index a2455ee..2b09887 100644
--- a/includes/core/class-prv-collector-registry.php
+++ b/includes/core/class-prv-collector-registry.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Registry for PR Vision data collectors and dashboard panels.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-config.php b/includes/core/class-prv-config.php
index 979def0..aa0f3de 100644
--- a/includes/core/class-prv-config.php
+++ b/includes/core/class-prv-config.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Configuration getters and default-seeding for PR Vision.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-cost-ledger.php b/includes/core/class-prv-cost-ledger.php
index a1c7fb9..aba51a2 100644
--- a/includes/core/class-prv-cost-ledger.php
+++ b/includes/core/class-prv-cost-ledger.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Month-to-date cost tracking and budget-cap enforcement.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-cron.php b/includes/core/class-prv-cron.php
index dcf1f52..bef54d0 100644
--- a/includes/core/class-prv-cron.php
+++ b/includes/core/class-prv-cron.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * WP-Cron management for the weekly AI-visibility probe.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-deactivator.php b/includes/core/class-prv-deactivator.php
index 53248a2..1cb2ea8 100644
--- a/includes/core/class-prv-deactivator.php
+++ b/includes/core/class-prv-deactivator.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Plugin deactivation handler.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-plugin.php b/includes/core/class-prv-plugin.php
index 9e14e42..f6f9e41 100644
--- a/includes/core/class-prv-plugin.php
+++ b/includes/core/class-prv-plugin.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Main orchestrator for the PR Vision plugin.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-probe-result.php b/includes/core/class-prv-probe-result.php
index 89ed87b..9ba7acb 100644
--- a/includes/core/class-prv-probe-result.php
+++ b/includes/core/class-prv-probe-result.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Immutable value object returned by every probe provider.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/core/class-prv-probe-runner.php b/includes/core/class-prv-probe-runner.php
index d33ee18..03f914a 100644
--- a/includes/core/class-prv-probe-runner.php
+++ b/includes/core/class-prv-probe-runner.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Orchestrates a full probe run across peptides, intents, and models.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
@@ -86,7 +91,7 @@ class PRV_Probe_Runner {
 						$result = $provider->probe( $query );
 					} catch ( \Exception $e ) {
 						// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
-					error_log( sprintf( 'PRV: probe failed [%s / %s]: %s', $model, $peptide['slug'], $e->getMessage() ) );
+						error_log( sprintf( 'PRV: probe failed [%s / %s]: %s', $model, $peptide['slug'], $e->getMessage() ) );
 						++$counts['skipped_error'];
 						continue;
 					}
@@ -107,11 +112,11 @@ class PRV_Probe_Runner {
 	/**
 	 * Persist a single probe result to the database.
 	 *
-	 * @param string          $run_id     UUID for this run.
-	 * @param array<string,string> $peptide Peptide config with slug and label.
-	 * @param string          $model      Model identifier.
-	 * @param string          $intent_tpl Raw intent template string.
-	 * @param PRV_Probe_Result $result    Probe result.
+	 * @param string               $run_id     UUID for this run.
+	 * @param array<string,string> $peptide    Peptide config with slug and label.
+	 * @param string               $model      Model identifier.
+	 * @param string               $intent_tpl Raw intent template string.
+	 * @param PRV_Probe_Result     $result     Probe result.
 	 *
 	 * @return int Inserted row ID, or 0 on failure.
 	 */
diff --git a/includes/core/class-prv-table-manager.php b/includes/core/class-prv-table-manager.php
index 81592c4..e18c41d 100644
--- a/includes/core/class-prv-table-manager.php
+++ b/includes/core/class-prv-table-manager.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Database table creation and schema versioning for PR Vision.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/panel/class-prv-ai-visibility-panel.php b/includes/panel/class-prv-ai-visibility-panel.php
index 3ccf5df..c0fc081 100644
--- a/includes/panel/class-prv-ai-visibility-panel.php
+++ b/includes/panel/class-prv-ai-visibility-panel.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * AI-visibility dashboard panel renderer.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/panel/interface-prv-dashboard-panel.php b/includes/panel/interface-prv-dashboard-panel.php
index 9375c6a..20741a2 100644
--- a/includes/panel/interface-prv-dashboard-panel.php
+++ b/includes/panel/interface-prv-dashboard-panel.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Contract for all PR Vision dashboard panels.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/providers/class-prv-citation-detector.php b/includes/providers/class-prv-citation-detector.php
index edc8fad..eaf4a44 100644
--- a/includes/providers/class-prv-citation-detector.php
+++ b/includes/providers/class-prv-citation-detector.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Detects whether peptiderepo.com appears in LLM source citations.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/providers/class-prv-gateway-client.php b/includes/providers/class-prv-gateway-client.php
index d552ea0..df6d21d 100644
--- a/includes/providers/class-prv-gateway-client.php
+++ b/includes/providers/class-prv-gateway-client.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Cloudflare AI Gateway HTTP client shared by all providers.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/providers/class-prv-openrouter-provider.php b/includes/providers/class-prv-openrouter-provider.php
index 72aebec..ad9c02b 100644
--- a/includes/providers/class-prv-openrouter-provider.php
+++ b/includes/providers/class-prv-openrouter-provider.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Generic OpenRouter provider for GPT-search and Gemini-search models.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/providers/class-prv-perplexity-provider.php b/includes/providers/class-prv-perplexity-provider.php
index be564bb..b6f5a53 100644
--- a/includes/providers/class-prv-perplexity-provider.php
+++ b/includes/providers/class-prv-perplexity-provider.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Perplexity sonar provider — primary citation signal.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**
diff --git a/includes/providers/interface-prv-probe-provider.php b/includes/providers/interface-prv-probe-provider.php
index 1598d1e..33c85f0 100644
--- a/includes/providers/interface-prv-probe-provider.php
+++ b/includes/providers/interface-prv-probe-provider.php
@@ -1,5 +1,10 @@
 <?php
-/** @package PrVision */
+/**
+ * Contract for all LLM probe providers.
+ *
+ * @package PrVision
+ */
+
 declare(strict_types=1);
 
 /**