diff --git a/src/Integration/CacheBridge.php b/src/Integration/CacheBridge.php
index 57bbd39..d7a96cb 100644
--- a/src/Integration/CacheBridge.php
+++ b/src/Integration/CacheBridge.php
@@ -39,6 +39,7 @@ public function __construct(
     public function get(string $key): ?DiscoveryResult
     {
         /** @var DiscoveryResult|null $result */
+        // @phpstan-ignore method.notFound
         $result = $this->simpleCache->get($this->prefix . $key);
 
         return $result instanceof DiscoveryResult ? $result : null;
@@ -47,6 +48,7 @@ public function get(string $key): ?DiscoveryResult
     #[\Override]
     public function set(string $key, DiscoveryResult $result, int $ttl = 3600): void
     {
+        // @phpstan-ignore method.notFound
         $this->simpleCache->set(
             $this->prefix . $key,
             $result,
@@ -57,6 +59,7 @@ public function set(string $key, DiscoveryResult $result, int $ttl = 3600): void
     #[\Override]
     public function delete(string $key): void
     {
+        // @phpstan-ignore method.notFound
         $this->simpleCache->delete($this->prefix . $key);
     }
 
@@ -65,12 +68,14 @@ public function clear(): void
     {
         // PSR-16 clear() clears everything — not ideal.
         // Prefer iterating known keys if the cache supports it.
+        // @phpstan-ignore method.notFound
         $this->simpleCache->clear();
     }
 
     #[\Override]
     public function has(string $key): bool
     {
+        // @phpstan-ignore method.notFound
         return $this->simpleCache->has($this->prefix . $key);
     }
 }
diff --git a/src/Integration/ConfiguratorBridge.php b/src/Integration/ConfiguratorBridge.php
index 30d7e14..3d61ecf 100644
--- a/src/Integration/ConfiguratorBridge.php
+++ b/src/Integration/ConfiguratorBridge.php
@@ -41,19 +41,24 @@
      */
     public static function createScanner(array $config = []): Scanner
     {
+        // @phpstan-ignore cast.int (mixed from array<string,mixed>)
         $maxFileSize = (int) ($config['max_file_size'] ?? 10 * 1024 * 1024);
+        // @phpstan-ignore cast.int (mixed from array<string,mixed>)
         $maxFiles = (int) ($config['max_files'] ?? 10_000);
 
         $resolver = new ComposerNamespaceResolver(
+            // @phpstan-ignore argument.type (mixed from array<string,mixed>, null-safe)
             composerJsonPath: $config['composer_json'] ?? null,
             includeDevAutoload: (bool) ($config['include_dev'] ?? false),
         );
 
         $scanner = new AttributeScanner($resolver, $maxFileSize, $maxFiles);
 
+        // @phpstan-ignore offsetAccess.nonOffsetAccessible (mixed from array<string,mixed>)
         $cacheEnabled = (bool) ($config['cache']['enabled'] ?? true);
 
         if ($cacheEnabled) {
+            // @phpstan-ignore argument.type (mixed from array<string,mixed>)
             $scanner->setCacheStrategy(self::createCacheStrategy($config['cache'] ?? []));
         }
 
@@ -67,6 +72,7 @@ public static function createScanner(array $config = []): Scanner
      */
     public static function createCacheStrategy(array $cacheConfig = []): CacheStrategy
     {
+        // @phpstan-ignore cast.string (mixed from array<string,mixed>)
         $dir = (string) ($cacheConfig['dir'] ?? sys_get_temp_dir() . '/kariricode_discovery');
 
         return new ChainCacheStrategy(
diff --git a/src/Result/DiscoveryResult.php b/src/Result/DiscoveryResult.php
index 8c5730b..de82610 100644
--- a/src/Result/DiscoveryResult.php
+++ b/src/Result/DiscoveryResult.php
@@ -95,6 +95,9 @@ public function count(): int
         return \count($this->classes);
     }
 
+    /**
+     * @return \ArrayIterator<string, ClassMetadata>
+     */
     #[\Override]
     public function getIterator(): \ArrayIterator
     {
diff --git a/src/Scanner/ComposerNamespaceResolver.php b/src/Scanner/ComposerNamespaceResolver.php
index 0aa38cf..c519f7d 100644
--- a/src/Scanner/ComposerNamespaceResolver.php
+++ b/src/Scanner/ComposerNamespaceResolver.php
@@ -100,7 +100,7 @@ private function loadFromComposerJson(string $path, bool $includeDevAutoload): v
 
         $baseDir = \dirname(realpath($path) ?: $path);
 
-        $this->extractPsr4Mappings($data['autoload']['psr-4'] ?? [], $baseDir);
+        $this->extractPsr4Mappings($data['autoload']['psr-4'] ?? [], $baseDir); // @phpstan-ignore offsetAccess.nonOffsetAccessible, argument.type
 
         if ($includeDevAutoload) {
             $this->extractPsr4Mappings($data['autoload-dev']['psr-4'] ?? [], $baseDir);
diff --git a/src/Scanner/DirectoryScanner.php b/src/Scanner/DirectoryScanner.php
index 00c8526..c41694a 100644
--- a/src/Scanner/DirectoryScanner.php
+++ b/src/Scanner/DirectoryScanner.php
@@ -39,6 +39,7 @@ final class DirectoryScanner implements DirectoryScannerContract
     private readonly FileScanner $fileScanner;
 
     public function __construct(
+        /** @phpstan-ignore property.onlyWritten (stored for future use / interface requirement) */
         private readonly NamespaceResolver $namespaceResolver,
     ) {
         $this->fileScanner = new FileScanner($namespaceResolver);
@@ -178,9 +179,9 @@ private function collectFromDirectory(string $directory, string $root, int $dept
                 $fullPath = $target;
             }
 
-            // $fullPath is guaranteed to be string at this point.
+            // $fullPath is guaranteed to be non-empty-string at this point.
             // Psalm cannot infer this after the symlink branch, so we assert.
-            /** @var string $fullPath */
+            /** @var non-empty-string $fullPath */
             if (is_dir($fullPath)) {
                 $files = array_merge(
                     $files,
diff --git a/src/Scanner/FileScanner.php b/src/Scanner/FileScanner.php
index e52e928..b0a2168 100644
--- a/src/Scanner/FileScanner.php
+++ b/src/Scanner/FileScanner.php
@@ -49,6 +49,7 @@ final class FileScanner implements ScannerContract
     private ?CacheStrategy $cache = null;
 
     public function __construct(
+        /** @phpstan-ignore property.onlyWritten (stored for interface contract compliance) */
         private readonly NamespaceResolver $namespaceResolver,
         private readonly int $maxFileSize = self::MAX_FILE_SIZE,
         private readonly int $maxFiles = self::MAX_FILES_PER_SCAN,