PHPCS compliance: fix pre-existing violations exposed by gating the lint step

All violations were present in v0.1.0 and hidden by continue-on-error.
Now that PHPCS gates the build (P2-B), they must be fixed.

- Add file-level @package doc comment to all PHP files (file doc requirement)
- Add short descriptions to @var and constructor docblocks throughout
- Fix @param type spacing throughout (PHPCS alignment rules)
- Expand phpcs:ignore lines to include NoCaching where DirectQuery is already
  suppressed (uninstall.php, cost-ledger, table-manager, collector)
- Suppress EscapeOutput.ExceptionNotEscaped on RuntimeException messages
  (exception strings are not HTML output)
- Suppress error_log_error_log on the probe-runner failure log
- Replace date() with gmdate() in panel (timezone-aware per WP standard)
- Convert inline associative arrays to multi-line in config (WP array style)
- Fix double-arrow alignment in probe-runner counts and insert arrays
- Fix double-space before ?? in provider constructors
- Expand phpcs:ignore for  reads to include MissingUnslash
- Fix $counts++ to ++$counts (prefix increment per WP standard)
- Fix V1/v1 capitalisation in interface doc long description

Agent-Session: pr-vision rename v0.1.1

includes/collector/class-prv-ai-visibility-collector.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -26,11 +27,15 @@ declare(strict_types=1);
 class PRV_Ai_Visibility_Collector implements PRV_Data_Collector {
 
 	/**
+	 * Budget ledger for MTD cost lookup.
+	 *
 	 * @var PRV_Cost_Ledger
 	 */
 	private PRV_Cost_Ledger $ledger;
 
 	/**
+	 * Constructor.
+	 *
 	 * @param PRV_Cost_Ledger|null $ledger Injected for testing.
 	 */
 	public function __construct( ?PRV_Cost_Ledger $ledger = null ) {
@@ -71,7 +76,7 @@ class PRV_Ai_Visibility_Collector implements PRV_Data_Collector {
 		$trendline = array();
 		foreach ( (array) $run_rows as $row ) {
 			$trendline[] = array(
-				'run_id'      => (string) $row['run_id'],
+				'run_id'     => (string) $row['run_id'],
 				'captured_at' => (string) $row['captured_at'],
 				'score'       => $this->compute_score(
 					(int) $row['cited_count'],

includes/collector/interface-prv-data-collector.php

@@ -1,10 +1,11 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
  * Seam: contract for all PR Vision data collectors.
  *
- * v1 implements only PRV_Ai_Visibility_Collector. Future collectors
+ * V1 implements only PRV_Ai_Visibility_Collector. Future collectors
  * (keyword rankings, schema coverage, technical-SEO) implement this
  * interface and register themselves with PRV_Collector_Registry without
  * changing the dashboard shell.

includes/core/class-prv-activator.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/core/class-prv-admin-page.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -123,10 +124,10 @@ class PRV_Admin_Page {
 
 		$redirect = add_query_arg(
 			array(
-				'page'           => self::MENU_SLUG,
+				'page'        => self::MENU_SLUG,
-				'prv_run_done'   => 1,
+				'prv_run_done' => 1,
-				'prv_probed'     => (int) $counts['probed'],
+				'prv_probed'  => (int) $counts['probed'],
-				'prv_skipped'    => (int) ( $counts['skipped_budget'] + $counts['skipped_error'] ),
+				'prv_skipped' => (int) ( $counts['skipped_budget'] + $counts['skipped_error'] ),
 			),
 			admin_url( 'admin.php' )
 		);
@@ -183,10 +184,10 @@ class PRV_Admin_Page {
 		if ( empty( $_GET['prv_run_done'] ) ) {
 			return;
 		}
-		// phpcs:ignore WordPress.Security.NonceVerification.Recommended
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash
-		$probed  = (int) ( $_GET['prv_probed'] ?? 0 );
+		$probed  = isset( $_GET['prv_probed'] ) ? absint( wp_unslash( $_GET['prv_probed'] ) ) : 0;
-		// phpcs:ignore WordPress.Security.NonceVerification.Recommended
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash
-		$skipped = (int) ( $_GET['prv_skipped'] ?? 0 );
+		$skipped = isset( $_GET['prv_skipped'] ) ? absint( wp_unslash( $_GET['prv_skipped'] ) ) : 0;
 
 		echo '<div class="notice notice-success is-dismissible"><p>';
 		echo esc_html(

includes/core/class-prv-autoloader.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/core/class-prv-collector-registry.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -60,7 +61,7 @@ class PRV_Collector_Registry {
 	/**
 	 * Register a data collector.
 	 *
-	 * @param PRV_Data_Collector $collector
+	 * @param PRV_Data_Collector $collector The collector to register.
 	 *
 	 * @return void
 	 */
@@ -71,8 +72,8 @@ class PRV_Collector_Registry {
 	/**
 	 * Register a dashboard panel.
 	 *
-	 * @param string               $key   Panel key (must match a collector key).
+	 * @param string              $key   Panel key (must match a collector key).
-	 * @param PRV_Dashboard_Panel  $panel
+	 * @param PRV_Dashboard_Panel $panel The panel to register.
 	 *
 	 * @return void
 	 */

includes/core/class-prv-config.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -85,18 +86,54 @@ class PRV_Config {
 	 */
 	private static function default_peptides(): array {
 		return array(
-			array( 'slug' => 'bpc-157', 'label' => 'BPC-157' ),
+			array(
-			array( 'slug' => 'tb-500', 'label' => 'TB-500' ),
+				'slug'  => 'bpc-157',
-			array( 'slug' => 'mk-677', 'label' => 'MK-677' ),
+				'label' => 'BPC-157',
-			array( 'slug' => 'cjc-1295', 'label' => 'CJC-1295' ),
+			),
-			array( 'slug' => 'ghrp-6', 'label' => 'GHRP-6' ),
+			array(
-			array( 'slug' => 'ipamorelin', 'label' => 'Ipamorelin' ),
+				'slug'  => 'tb-500',
-			array( 'slug' => 'semaglutide', 'label' => 'Semaglutide' ),
+				'label' => 'TB-500',
-			array( 'slug' => 'tirzepatide', 'label' => 'Tirzepatide' ),
+			),
-			array( 'slug' => 'selank', 'label' => 'Selank' ),
+			array(
-			array( 'slug' => 'semax', 'label' => 'Semax' ),
+				'slug'  => 'mk-677',
-			array( 'slug' => 'nad-plus', 'label' => 'NAD+' ),
+				'label' => 'MK-677',
-			array( 'slug' => 'aod-9604', 'label' => 'AOD-9604' ),
+			),
+			array(
+				'slug'  => 'cjc-1295',
+				'label' => 'CJC-1295',
+			),
+			array(
+				'slug'  => 'ghrp-6',
+				'label' => 'GHRP-6',
+			),
+			array(
+				'slug'  => 'ipamorelin',
+				'label' => 'Ipamorelin',
+			),
+			array(
+				'slug'  => 'semaglutide',
+				'label' => 'Semaglutide',
+			),
+			array(
+				'slug'  => 'tirzepatide',
+				'label' => 'Tirzepatide',
+			),
+			array(
+				'slug'  => 'selank',
+				'label' => 'Selank',
+			),
+			array(
+				'slug'  => 'semax',
+				'label' => 'Semax',
+			),
+			array(
+				'slug'  => 'nad-plus',
+				'label' => 'NAD+',
+			),
+			array(
+				'slug'  => 'aod-9604',
+				'label' => 'AOD-9604',
+			),
 		);
 	}
 

includes/core/class-prv-cost-ledger.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -60,8 +61,8 @@ class PRV_Cost_Ledger {
 	 * @return bool True when the call can proceed within budget.
 	 */
 	public function can_afford( float $estimated_cost_usd ): bool {
-		$cap    = PRV_Config::get_monthly_budget_usd();
+		$cap   = PRV_Config::get_monthly_budget_usd();
-		$spent  = $this->get_month_to_date_usd();
+		$spent = $this->get_month_to_date_usd();
 		return ( $spent + $estimated_cost_usd ) <= $cap;
 	}
 
@@ -95,7 +96,7 @@ class PRV_Cost_Ledger {
 
 		$table = PRV_Table_Manager::get_table_name();
 
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
 		$result = $wpdb->update(
 			$table,
 			array( 'cost_usd' => number_format( $cost_usd, 8, '.', '' ) ),

includes/core/class-prv-cron.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/core/class-prv-deactivator.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/core/class-prv-plugin.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/core/class-prv-probe-result.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -18,11 +19,13 @@ declare(strict_types=1);
 class PRV_Probe_Result {
 
 	/**
-	 * @param string        $raw_excerpt    First ~500 chars of the LLM's response.
+	 * Constructor.
-	 * @param string[]      $source_domains Domains extracted from the provider's citations.
+	 *
-	 * @param bool          $cited          Whether peptiderepo.com appears in source_domains.
+	 * @param string   $raw_excerpt    First ~500 chars of the LLM's response.
-	 * @param int|null      $our_position   1-based position of peptiderepo.com in sources, or null.
+	 * @param string[] $source_domains Domains extracted from the provider's citations.
-	 * @param float         $cost_usd       Estimated call cost in USD.
+	 * @param bool     $cited          Whether peptiderepo.com appears in source_domains.
+	 * @param int|null $our_position   1-based position of peptiderepo.com in sources, or null.
+	 * @param float    $cost_usd       Estimated call cost in USD.
 	 */
 	public function __construct(
 		private readonly string $raw_excerpt,
@@ -33,6 +36,8 @@ class PRV_Probe_Result {
 	) {}
 
 	/**
+	 * Get the raw LLM response excerpt.
+	 *
 	 * @return string
 	 */
 	public function get_raw_excerpt(): string {
@@ -40,6 +45,8 @@ class PRV_Probe_Result {
 	}
 
 	/**
+	 * Get the extracted source domains.
+	 *
 	 * @return string[]
 	 */
 	public function get_source_domains(): array {
@@ -47,6 +54,8 @@ class PRV_Probe_Result {
 	}
 
 	/**
+	 * Whether peptiderepo.com was cited.
+	 *
 	 * @return bool
 	 */
 	public function is_cited(): bool {
@@ -54,6 +63,8 @@ class PRV_Probe_Result {
 	}
 
 	/**
+	 * Get 1-based position of peptiderepo.com in source list.
+	 *
 	 * @return int|null 1-based position or null when not cited.
 	 */
 	public function get_our_position(): ?int {
@@ -61,6 +72,8 @@ class PRV_Probe_Result {
 	}
 
 	/**
+	 * Get the estimated cost of this probe call.
+	 *
 	 * @return float Estimated cost in USD.
 	 */
 	public function get_cost_usd(): float {

includes/core/class-prv-probe-runner.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -23,11 +24,15 @@ declare(strict_types=1);
 class PRV_Probe_Runner {
 
 	/**
+	 * Budget ledger for cost-cap enforcement.
+	 *
 	 * @var PRV_Cost_Ledger
 	 */
 	private PRV_Cost_Ledger $ledger;
 
 	/**
+	 * Constructor.
+	 *
 	 * @param PRV_Cost_Ledger|null $ledger Injected for testing; auto-created otherwise.
 	 */
 	public function __construct( ?PRV_Cost_Ledger $ledger = null ) {
@@ -53,9 +58,9 @@ class PRV_Probe_Runner {
 		$models   = PRV_Config::get_models();
 
 		$counts = array(
-			'probed'          => 0,
+			'probed'         => 0,
-			'skipped_budget'  => 0,
+			'skipped_budget' => 0,
-			'skipped_error'   => 0,
+			'skipped_error'  => 0,
 		);
 
 		foreach ( $peptides as $peptide ) {
@@ -66,22 +71,23 @@ class PRV_Probe_Runner {
 					$provider = $this->resolve_provider( $model );
 
 					if ( null === $provider || ! $provider->is_configured() ) {
-						$counts['skipped_error']++;
+						++$counts['skipped_error'];
 						continue;
 					}
 
 					// Budget pre-check.
 					$estimated = $this->get_estimated_cost( $model );
 					if ( ! $this->ledger->can_afford( $estimated ) ) {
-						$counts['skipped_budget']++;
+						++$counts['skipped_budget'];
 						continue;
 					}
 
 					try {
 						$result = $provider->probe( $query );
 					} catch ( \Exception $e ) {
-						error_log( sprintf( 'PRV: probe failed [%s / %s]: %s', $model, $peptide['slug'], $e->getMessage() ) );
+						// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
-						$counts['skipped_error']++;
+					error_log( sprintf( 'PRV: probe failed [%s / %s]: %s', $model, $peptide['slug'], $e->getMessage() ) );
+						++$counts['skipped_error'];
 						continue;
 					}
 
@@ -90,7 +96,7 @@ class PRV_Probe_Runner {
 						$this->ledger->update_row_cost( $row_id, $result->get_cost_usd() );
 					}
 
-					$counts['probed']++;
+					++$counts['probed'];
 				}
 			}
 		}
@@ -101,11 +107,11 @@ class PRV_Probe_Runner {
 	/**
 	 * Persist a single probe result to the database.
 	 *
-	 * @param string               $run_id      UUID for this run.
+	 * @param string          $run_id     UUID for this run.
-	 * @param array{slug:string, label:string} $peptide Peptide config.
+	 * @param array<string,string> $peptide Peptide config with slug and label.
-	 * @param string               $model       Model identifier.
+	 * @param string          $model      Model identifier.
-	 * @param string               $intent_tpl  Raw intent template string.
+	 * @param string          $intent_tpl Raw intent template string.
-	 * @param PRV_Probe_Result     $result      Probe result.
+	 * @param PRV_Probe_Result $result    Probe result.
 	 *
 	 * @return int Inserted row ID, or 0 on failure.
 	 */
@@ -118,17 +124,17 @@ class PRV_Probe_Runner {
 		$wpdb->insert(
 			$table,
 			array(
-				'run_id'        => $run_id,
+				'run_id'         => $run_id,
-				'captured_at'   => current_time( 'mysql', true ),
+				'captured_at'    => current_time( 'mysql', true ),
-				'peptide_slug'  => $peptide['slug'],
+				'peptide_slug'   => $peptide['slug'],
-				'peptide_label' => $peptide['label'],
+				'peptide_label'  => $peptide['label'],
-				'model'         => $model,
+				'model'          => $model,
-				'prompt_intent' => $intent_tpl,
+				'prompt_intent'  => $intent_tpl,
-				'cited'         => $result->is_cited() ? 1 : 0,
+				'cited'          => $result->is_cited() ? 1 : 0,
-				'our_position'  => $result->get_our_position(),
+				'our_position'   => $result->get_our_position(),
 				'source_domains' => wp_json_encode( $result->get_source_domains() ),
-				'raw_excerpt'   => $result->get_raw_excerpt(),
+				'raw_excerpt'    => $result->get_raw_excerpt(),
-				'cost_usd'      => number_format( $result->get_cost_usd(), 8, '.', '' ),
+				'cost_usd'       => number_format( $result->get_cost_usd(), 8, '.', '' ),
 			),
 			array( '%s', '%s', '%s', '%s', '%s', '%s', '%d', '%d', '%s', '%s', '%s' )
 		);

includes/core/class-prv-table-manager.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -88,7 +89,7 @@ class PRV_Table_Manager {
 	public static function drop_table(): void {
 		global $wpdb;
 		$table = $wpdb->prefix . self::TABLE_BASE;
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.NoCaching
 		$wpdb->query( "DROP TABLE IF EXISTS {$table}" );
 	}
 }

includes/panel/class-prv-ai-visibility-panel.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -30,11 +31,11 @@ class PRV_Ai_Visibility_Panel implements PRV_Dashboard_Panel {
 	 * @return void
 	 */
 	public function render( array $data ): void {
-		$trendline       = is_array( $data['trendline'] ?? null ) ? $data['trendline'] : array();
+		$trendline   = is_array( $data['trendline'] ?? null ) ? $data['trendline'] : array();
-		$standings       = is_array( $data['standings'] ?? null ) ? $data['standings'] : array();
+		$standings   = is_array( $data['standings'] ?? null ) ? $data['standings'] : array();
-		$last_run_at     = isset( $data['last_run_at'] ) && $data['last_run_at'] ? esc_html( (string) $data['last_run_at'] ) : esc_html__( 'Never', 'pr-vision' );
+		$last_run_at = isset( $data['last_run_at'] ) && $data['last_run_at'] ? esc_html( (string) $data['last_run_at'] ) : esc_html__( 'Never', 'pr-vision' );
-		$mtd_cost        = isset( $data['mtd_cost_usd'] ) ? (float) $data['mtd_cost_usd'] : 0.0;
+		$mtd_cost    = isset( $data['mtd_cost_usd'] ) ? (float) $data['mtd_cost_usd'] : 0.0;
-		$cap             = isset( $data['monthly_cap_usd'] ) ? (float) $data['monthly_cap_usd'] : PRV_DEFAULT_MONTHLY_BUDGET_USD;
+		$cap         = isset( $data['monthly_cap_usd'] ) ? (float) $data['monthly_cap_usd'] : PRV_DEFAULT_MONTHLY_BUDGET_USD;
 
 		$this->render_proxy_note();
 		$this->render_meta_bar( $last_run_at, $mtd_cost, $cap );
@@ -96,7 +97,7 @@ class PRV_Ai_Visibility_Panel implements PRV_Dashboard_Panel {
 		$labels = array();
 		$scores = array();
 		foreach ( $trendline as $point ) {
-			$labels[] = esc_js( date( 'M j', strtotime( $point['captured_at'] ) ) );
+			$labels[] = esc_js( gmdate( 'M j', (int) strtotime( $point['captured_at'] ) ) );
 			$scores[] = (float) $point['score'];
 		}
 
@@ -104,8 +105,10 @@ class PRV_Ai_Visibility_Panel implements PRV_Dashboard_Panel {
 		$scores_json = wp_json_encode( $scores );
 
 		echo '<canvas id="prv-trendline-chart" height="120"></canvas>';
+		// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
 		echo '<script>document.addEventListener("DOMContentLoaded",function(){';
 		echo 'var ctx=document.getElementById("prv-trendline-chart").getContext("2d");';
+		// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
 		echo 'new Chart(ctx,{type:"line",data:{labels:' . $labels_json . ',datasets:[{label:"Visibility Score",data:' . $scores_json . ',borderColor:"#2271b1",tension:0.3,fill:false}]},options:{scales:{y:{min:0,max:1,title:{display:true,text:"Score"}}},plugins:{legend:{display:false}}}});';
 		echo '});</script>';
 		echo '</div>';

includes/panel/interface-prv-dashboard-panel.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/providers/class-prv-citation-detector.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

includes/providers/class-prv-gateway-client.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -97,13 +98,14 @@ class PRV_Gateway_Client {
 					$last_error = sprintf( 'HTTP %d', $status );
 					if ( $attempt < PRV_MAX_RETRIES ) {
 						$retry_after = wp_remote_retrieve_header( $response, 'retry-after' );
-						$delay = $retry_after ? min( (int) $retry_after, 60 ) : PRV_RETRY_BASE_DELAY_SECONDS * (int) pow( 2, $attempt - 1 );
+						$delay       = $retry_after ? min( (int) $retry_after, 60 ) : PRV_RETRY_BASE_DELAY_SECONDS * (int) pow( 2, $attempt - 1 );
 						sleep( $delay );
 					}
 					continue;
 				}
 
 				if ( $status >= 400 ) {
+					// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped
 					throw new \RuntimeException(
 						sprintf( 'PR Vision gateway HTTP %d: %s', $status, substr( $raw_body, 0, 300 ) )
 					);
@@ -120,6 +122,7 @@ class PRV_Gateway_Client {
 			remove_action( 'http_api_curl', $curl_filter, 99 );
 		}
 
+		// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped
 		throw new \RuntimeException(
 			sprintf( 'PR Vision: gateway failed after %d attempts. Last: %s', PRV_MAX_RETRIES, $last_error )
 		);

includes/providers/class-prv-openrouter-provider.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -33,35 +34,44 @@ class PRV_OpenRouter_Provider implements PRV_Probe_Provider {
 	const ESTIMATED_COST_PER_PROBE = 0.003;
 
 	/**
-	 * @var string OpenRouter model identifier (e.g. "openai/gpt-4o-search-preview").
+	 * OpenRouter model identifier (e.g. "openai/gpt-4o-search-preview").
+	 *
+	 * @var string
 	 */
 	private string $model;
 
 	/**
+	 * HTTP gateway client.
+	 *
 	 * @var PRV_Gateway_Client
 	 */
 	private PRV_Gateway_Client $gateway;
 
 	/**
+	 * Citation domain detector.
+	 *
 	 * @var PRV_Citation_Detector
 	 */
 	private PRV_Citation_Detector $detector;
 
 	/**
-	 * @param string                 $model    OpenRouter model identifier.
+	 * Constructor.
+	 *
+	 * @param string                     $model    OpenRouter model identifier.
 	 * @param PRV_Gateway_Client|null    $gateway  Injected for testing.
 	 * @param PRV_Citation_Detector|null $detector Injected for testing.
 	 */
 	public function __construct( string $model, ?PRV_Gateway_Client $gateway = null, ?PRV_Citation_Detector $detector = null ) {
 		$this->model    = $model;
-		$this->gateway  = $gateway  ?? new PRV_Gateway_Client();
+		$this->gateway  = $gateway ?? new PRV_Gateway_Client();
 		$this->detector = $detector ?? new PRV_Citation_Detector();
 	}
 
 	/**
 	 * {@inheritDoc}
 	 *
-	 * @param string $query
+	 * @param string $query The search query to probe.
+	 *
 	 * @return PRV_Probe_Result
 	 * @throws \RuntimeException On permanent API failure.
 	 */
@@ -71,7 +81,10 @@ class PRV_OpenRouter_Provider implements PRV_Probe_Provider {
 		$body = array(
 			'model'      => $this->model,
 			'messages'   => array(
-				array( 'role' => 'user', 'content' => $query ),
+				array(
+					'role'    => 'user',
+					'content' => $query,
+				),
 			),
 			'max_tokens' => 512,
 		);

includes/providers/class-prv-perplexity-provider.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**
@@ -36,21 +37,27 @@ class PRV_Perplexity_Provider implements PRV_Probe_Provider {
 	const ESTIMATED_COST_PER_PROBE = 0.005;
 
 	/**
+	 * HTTP gateway client.
+	 *
 	 * @var PRV_Gateway_Client
 	 */
 	private PRV_Gateway_Client $gateway;
 
 	/**
+	 * Citation domain detector.
+	 *
 	 * @var PRV_Citation_Detector
 	 */
 	private PRV_Citation_Detector $detector;
 
 	/**
+	 * Constructor.
+	 *
 	 * @param PRV_Gateway_Client|null    $gateway  Injected for testing; auto-created otherwise.
 	 * @param PRV_Citation_Detector|null $detector Injected for testing; auto-created otherwise.
 	 */
 	public function __construct( ?PRV_Gateway_Client $gateway = null, ?PRV_Citation_Detector $detector = null ) {
-		$this->gateway  = $gateway  ?? new PRV_Gateway_Client();
+		$this->gateway  = $gateway ?? new PRV_Gateway_Client();
 		$this->detector = $detector ?? new PRV_Citation_Detector();
 	}
 
@@ -60,7 +67,7 @@ class PRV_Perplexity_Provider implements PRV_Probe_Provider {
 	 * Sends the query as a user message to perplexity/sonar via OpenRouter.
 	 * Parses the citations[] array from the OpenRouter response envelope.
 	 *
-	 * @param string $query
+	 * @param string $query The search query to probe.
 	 *
 	 * @return PRV_Probe_Result
 	 * @throws \RuntimeException On permanent API failure.
@@ -69,9 +76,12 @@ class PRV_Perplexity_Provider implements PRV_Probe_Provider {
 		$api_key = $this->resolve_api_key();
 
 		$body = array(
-			'model'    => self::MODEL,
+			'model'      => self::MODEL,
-			'messages' => array(
+			'messages'   => array(
-				array( 'role' => 'user', 'content' => $query ),
+				array(
+					'role'    => 'user',
+					'content' => $query,
+				),
 			),
 			'max_tokens' => 512,
 		);
@@ -135,11 +145,12 @@ class PRV_Perplexity_Provider implements PRV_Probe_Provider {
 	/**
 	 * Retrieve the OpenRouter API key from wp-config constants.
 	 *
-	 * @return string
+	 * @return string The API key.
 	 * @throws \RuntimeException When the constant is not defined or empty.
 	 */
 	private function resolve_api_key(): string {
 		if ( ! defined( 'PRV_OPENROUTER_API_KEY' ) || '' === PRV_OPENROUTER_API_KEY ) {
+			// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped
 			throw new \RuntimeException(
 				__( 'PRV_OPENROUTER_API_KEY constant is not defined. Add it to wp-config.php.', 'pr-vision' )
 			);

includes/providers/interface-prv-probe-provider.php

@@ -1,4 +1,5 @@
 <?php
+/** @package PrVision */
 declare(strict_types=1);
 
 /**

pr-vision.php

@@ -13,6 +13,7 @@
  * @see ARCHITECTURE.md — Full data flow and file tree.
  * @see CONVENTIONS.md  — Naming patterns and extension guide.
  * @see CONTEXT.md      — Domain glossary incl. the visibility score formula.
+ * @package PrVision
  */
 
 declare(strict_types=1);
@@ -29,22 +30,22 @@ define( 'PRV_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );
 define( 'PRV_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
 define( 'PRV_SCHEMA_VERSION', 1 );
 
-/** @var int Maximum HTTP retries for LLM API calls. */
+/** Maximum HTTP retries for LLM API calls. @var int */
 define( 'PRV_MAX_RETRIES', 3 );
 
-/** @var int API request timeout in seconds. */
+/** API request timeout in seconds. @var int */
 define( 'PRV_API_TIMEOUT_SECONDS', 60 );
 
-/** @var int Base backoff delay (seconds) between retries. */
+/** Base backoff delay (seconds) between retries. @var int */
 define( 'PRV_RETRY_BASE_DELAY_SECONDS', 2 );
 
-/** @var float Default monthly budget cap in USD. */
+/** Default monthly budget cap in USD. @var float */
 define( 'PRV_DEFAULT_MONTHLY_BUDGET_USD', 5.0 );
 
-/** @var string WP-Cron hook name for the weekly probe run. */
+/** WP-Cron hook name for the weekly probe run. @var string */
 define( 'PRV_CRON_HOOK', 'prv_weekly_probe' );
 
-/** @var string The site we are tracking citations for. */
+/** The site we are tracking citations for. @var string */
 define( 'PRV_TARGET_DOMAIN', 'peptiderepo.com' );
 
 /* ── Autoloader ───────────────────────────────────────────────────────── */

uninstall.php

@@ -8,6 +8,7 @@
  *
  * @see ARCHITECTURE.md — §Uninstall specification.
  * @see class-prv-deactivator.php — Clears cron on deactivation.
+ * @package PrVision
  */
 
 if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
@@ -19,12 +20,12 @@ global $wpdb;
 /* ── 1. Drop the custom table ─────────────────────────────────────── */
 
 $table = $wpdb->prefix . 'prv_ai_visibility';
-// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.NoCaching
 $wpdb->query( "DROP TABLE IF EXISTS {$table}" );
 
 /* ── 2. Delete all prv_ prefixed options ──────────────────────────── */
 
-// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
 $wpdb->query(
 	"DELETE FROM {$wpdb->options} WHERE option_name LIKE 'prv\_%'"
 );