diff --git a/Benchmarks/AdaECSBenchmarks/AdaECSBenchmarks.swift b/Benchmarks/AdaECSBenchmarks/AdaECSBenchmarks.swift
new file mode 100644
index 000000000..be8927b40
--- /dev/null
+++ b/Benchmarks/AdaECSBenchmarks/AdaECSBenchmarks.swift
@@ -0,0 +1,242 @@
+import AdaECS
+import Benchmark
+
+// MARK: - Components
+
+@Component
+private struct Position {
+    var x: Float
+    var y: Float
+}
+
+@Component
+private struct Velocity {
+    var x: Float
+    var y: Float
+}
+
+@Component
+private struct CompA {
+    var value: Float
+}
+
+@Component
+private struct CompB {
+    var value: Float
+}
+
+@Component
+private struct CompC {
+    var value: Float
+}
+
+@Component
+private struct FragData {
+    var value: Float
+}
+
+@Component
+private struct Matrix4x4 {
+    var m00: Float, m01: Float, m02: Float, m03: Float
+    var m10: Float, m11: Float, m12: Float, m13: Float
+    var m20: Float, m21: Float, m22: Float, m23: Float
+    var m30: Float, m31: Float, m32: Float, m33: Float
+}
+
+// MARK: - Constants
+
+private enum BenchConstants {
+    static let spawnEntities = 100_000
+    static let simpleIterEntities = 100_000
+    static let fragmentedEntitiesPerType = 33_334
+    static let heavyComputeEntities = 1_000
+    static let heavyComputeIterations = 100
+    static let addRemoveEntities = 100_000
+}
+
+// MARK: - Setup Helpers
+
+private func makeSimpleIterWorld(entityCount: Int) -> (World, Query<Ref<Position>, Velocity>) {
+    let world = World()
+    for i in 0..<entityCount {
+        world.spawn {
+            Position(x: Float(i), y: Float(i))
+            Velocity(x: 1, y: -1)
+        }
+    }
+
+    let query = Query<Ref<Position>, Velocity>()
+    query.update(from: world)
+
+    return (world, query)
+}
+
+private func makeFragmentedIterWorld(entitiesPerType: Int) -> (World, Query<Ref<FragData>>) {
+    let world = World()
+
+    for i in 0..<entitiesPerType {
+        world.spawn {
+            CompA(value: Float(i))
+            FragData(value: Float(i))
+        }
+    }
+    for i in 0..<entitiesPerType {
+        world.spawn {
+            CompB(value: Float(i))
+            FragData(value: Float(i))
+        }
+    }
+    for i in 0..<entitiesPerType {
+        world.spawn {
+            CompC(value: Float(i))
+            FragData(value: Float(i))
+        }
+    }
+
+    let query = Query<Ref<FragData>>()
+    query.update(from: world)
+
+    return (world, query)
+}
+
+private func makeHeavyComputeWorld(entityCount: Int) -> (World, Query<Ref<Matrix4x4>>) {
+    let world = World()
+    for _ in 0..<entityCount {
+        world.spawn {
+            Matrix4x4(
+                m00: 1, m01: 0, m02: 0, m03: 0,
+                m10: 0, m11: 1, m12: 0, m13: 0,
+                m20: 0, m21: 0, m22: 1, m23: 0,
+                m30: 0, m31: 0, m32: 0, m33: 1
+            )
+        }
+    }
+
+    let query = Query<Ref<Matrix4x4>>()
+    query.update(from: world)
+
+    return (world, query)
+}
+
+private func makeAddRemoveWorld(entityCount: Int) -> (World, [Entity.ID]) {
+    let world = World()
+    var ids: [Entity.ID] = []
+    ids.reserveCapacity(entityCount)
+
+    for i in 0..<entityCount {
+        let entity = world.spawn {
+            Position(x: Float(i), y: Float(i))
+        }
+        ids.append(entity.id)
+    }
+
+    return (world, ids)
+}
+
+// MARK: - Benchmarks
+
+let benchmarks: @Sendable () -> Void = {
+    Benchmark("AdaECS.Spawn") { benchmark in
+        // #region agent log
+        DebugBenchmarkLog.benchmarkPhase(name: "Spawn", phase: "start")
+        // #endregion
+        for _ in benchmark.scaledIterations {
+            let world = World()
+            for _ in 0..<BenchConstants.spawnEntities {
+                world.spawn()
+            }
+            blackHole(world)
+        }
+        // #region agent log
+        DebugBenchmarkLog.benchmarkPhase(name: "Spawn", phase: "end")
+        // #endregion
+    }
+
+    Benchmark(
+        "AdaECS.SimpleIter",
+        closure: { benchmark, state in
+            // #region agent log
+            DebugBenchmarkLog.benchmarkPhase(name: "SimpleIter", phase: "start")
+            // #endregion
+            let (world, query) = state
+            for _ in benchmark.scaledIterations {
+                query.forEach { position, velocity in
+                    position.x += velocity.x
+                    position.y += velocity.y
+                }
+            }
+            blackHole(world)
+            // #region agent log
+            DebugBenchmarkLog.benchmarkPhase(name: "SimpleIter", phase: "end")
+            // #endregion
+        },
+        setup: {
+            makeSimpleIterWorld(entityCount: BenchConstants.simpleIterEntities)
+        }
+    )
+
+    Benchmark(
+        "AdaECS.FragmentedIter",
+        closure: { benchmark, state in
+            // #region agent log
+            DebugBenchmarkLog.benchmarkPhase(name: "FragmentedIter", phase: "start")
+            // #endregion
+            let (world, query) = state
+            for _ in benchmark.scaledIterations {
+                for data in query {
+                    data.value *= 2.0
+                }
+            }
+            blackHole(world)
+            // #region agent log
+            DebugBenchmarkLog.benchmarkPhase(name: "FragmentedIter", phase: "end")
+            // #endregion
+        },
+        setup: {
+            makeFragmentedIterWorld(entitiesPerType: BenchConstants.fragmentedEntitiesPerType)
+        }
+    )
+
+    Benchmark(
+        "AdaECS.HeavyCompute",
+        closure: { benchmark, state in
+            let (world, query) = state
+            for _ in benchmark.scaledIterations {
+                for transform in query {
+                    for _ in 0..<BenchConstants.heavyComputeIterations {
+                        transform.m00 += 1.0
+                    }
+                }
+            }
+            blackHole(world)
+        },
+        setup: {
+            makeHeavyComputeWorld(entityCount: BenchConstants.heavyComputeEntities)
+        }
+    )
+
+    Benchmark(
+        "AdaECS.AddRemove",
+        closure: { benchmark, state in
+            // #region agent log
+            DebugBenchmarkLog.benchmarkPhase(name: "AddRemove", phase: "start")
+            // #endregion
+            let (world, ids) = state
+            for _ in benchmark.scaledIterations {
+                for id in ids {
+                    world.insert(Velocity(x: 1, y: -1), for: id)
+                }
+                for id in ids {
+                    world.remove(Velocity.self, from: id)
+                }
+            }
+            blackHole(world)
+            // #region agent log
+            DebugBenchmarkLog.benchmarkPhase(name: "AddRemove", phase: "end")
+            // #endregion
+        },
+        setup: {
+            makeAddRemoveWorld(entityCount: BenchConstants.addRemoveEntities)
+        }
+    )
+}
diff --git a/Package.swift b/Package.swift
index f0a72bb22..2ec807e96 100644
--- a/Package.swift
+++ b/Package.swift
@@ -775,6 +775,22 @@ targets += [
     )
 ]
 
+// MARK: - Benchmarks
+
+targets += [
+    .executableTarget(
+        name: "AdaECSBenchmarks",
+        dependencies: [
+            .product(name: "Benchmark", package: "package-benchmark"),
+            "AdaECS"
+        ],
+        path: "Benchmarks/AdaECSBenchmarks",
+        plugins: [
+            .plugin(name: "BenchmarkPlugin", package: "package-benchmark")
+        ]
+    )
+]
+
 // MARK: - Tests
 
 targets += [
@@ -903,6 +919,7 @@ package.dependencies += [
     .package(url: "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/apple/swift-atomics", from: "1.3.0"),
     .package(url: "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/the-swift-collective/zlib.git", from: "1.3.2"),
     .package(url: "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/swiftlang/swift-subprocess.git", branch: "0.2.1"),
+    .package(url: "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/ordo-one/package-benchmark", from: "1.29.0"),
     // TODO: SpectralDragon packages should move to AdaEngine
     .package(url: "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/SpectralDragon/Yams.git", revision: "fb676da"),
     .package(
@@ -985,12 +1002,12 @@ private extension Target {
             dependencies: [
                 "AdaEngine"
             ],
-            path: "Demos/\(path)/",
+            path: "Demos/",
             sources: [
-                "\(name).swift"
+                "\(path)/\(name).swift"
             ],
             resources: [
-                .copy("../Resources/")
+                .copy("Resources/")
             ],
             packageAccess: false
         )
diff --git a/README.md b/README.md
index a9551729f..0ceec5fc0 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/AdaEngine/AdaEngine/blob/main/LICENSE)
 [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2FAdaEngine%2FAdaEngine%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/AdaEngine/AdaEngine)
 [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2FAdaEngine%2FAdaEngine%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/AdaEngine/AdaEngine)
-
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/AdaEngine/AdaEngine)
 
 ## What is AdaEngine?
 
diff --git a/Sources/AdaECS/DebugBenchmarkLog.swift b/Sources/AdaECS/DebugBenchmarkLog.swift
new file mode 100644
index 000000000..0b03dd44f
--- /dev/null
+++ b/Sources/AdaECS/DebugBenchmarkLog.swift
@@ -0,0 +1,71 @@
+//
+//  DebugBenchmarkLog.swift
+//  AdaECS
+//
+//  Writes NDJSON to a file when CURSOR_DEBUG_LOG_PATH is set (for benchmark profiling).
+//
+
+import Foundation
+
+enum DebugBenchmarkLogCounter {
+    static var entitiesInsertCount = 0
+    static var insertNewEntityCount = 0
+    static var moveEntityToArchetypeCount = 0
+    static var queryEntityLookupCount = 0
+    static var querySetChunkCount = 0
+}
+
+public enum DebugBenchmarkLog {
+
+    private static let logPath = ProcessInfo.processInfo.environment["CURSOR_DEBUG_LOG_PATH"]
+    private static let sessionId = "ef35b1"
+
+    /// Append one NDJSON line when CURSOR_DEBUG_LOG_PATH is set. No-op otherwise.
+    public static func write(
+        location: String,
+        message: String,
+        data: [String: Any] = [:],
+        hypothesisId: String? = nil
+    ) {
+        guard let path = logPath, !path.isEmpty else { return }
+        let timestamp = Int(Date().timeIntervalSince1970 * 1000)
+        var payload: [String: Any] = [
+            "sessionId": sessionId,
+            "location": location,
+            "message": message,
+            "timestamp": timestamp
+        ]
+        if !data.isEmpty {
+            payload["data"] = data
+        }
+        if let hid = hypothesisId {
+            payload["hypothesisId"] = hid
+        }
+        guard let json = try? JSONSerialization.data(withJSONObject: payload),
+              let line = String(data: json, encoding: .utf8)
+        else { return }
+        let content = line + "\n"
+        guard let contentData = content.data(using: .utf8) else { return }
+        let url = URL(fileURLWithPath: path)
+        if !FileManager.default.fileExists(atPath: path) {
+            FileManager.default.createFile(atPath: path, contents: nil)
+        }
+        if let handle = try? FileHandle(forWritingTo: url) {
+            defer { try? handle.close() }
+            handle.seekToEndOfFile()
+            handle.write(contentData)
+        } else {
+            try? contentData.write(to: url, options: .atomic)
+        }
+    }
+
+    /// Call from benchmark to mark start/end of a benchmark (when CURSOR_DEBUG_LOG_PATH is set).
+    public static func benchmarkPhase(name: String, phase: String) {
+        write(
+            location: "AdaECSBenchmarks",
+            message: "benchmark_phase",
+            data: ["benchmark": name, "phase": phase],
+            hypothesisId: nil
+        )
+    }
+}
diff --git a/Sources/AdaECS/Query/Query.swift b/Sources/AdaECS/Query/Query.swift
index 19ad5b3e7..5a1b1455c 100644
--- a/Sources/AdaECS/Query/Query.swift
+++ b/Sources/AdaECS/Query/Query.swift
@@ -289,6 +289,17 @@ public struct FilterQueryIterator<
 
             let currentChunk = archetype.chunks.chunks[cursor.currentChunkIndex]
             if needsUpdateData {
+                // #region agent log
+                DebugBenchmarkLogCounter.querySetChunkCount += 1
+                if DebugBenchmarkLogCounter.querySetChunkCount % 100 == 0 {
+                    DebugBenchmarkLog.write(
+                        location: "Query.swift:next setChunk",
+                        message: "query_set_chunk",
+                        data: ["count": DebugBenchmarkLogCounter.querySetChunkCount],
+                        hypothesisId: "H4"
+                    )
+                }
+                // #endregion
                 B.setChunk(
                     states: states,
                     fetches: &fetches,
@@ -318,6 +329,17 @@ public struct FilterQueryIterator<
                 continue
             }
 
+            // #region agent log
+            DebugBenchmarkLogCounter.queryEntityLookupCount += 1
+            if DebugBenchmarkLogCounter.queryEntityLookupCount % 25_000 == 0 {
+                DebugBenchmarkLog.write(
+                    location: "Query.swift:next entityLookup",
+                    message: "query_entity_lookup",
+                    data: ["count": DebugBenchmarkLogCounter.queryEntityLookupCount],
+                    hypothesisId: "H3"
+                )
+            }
+            // #endregion
             guard let location = state.entities.entities[entityId] else {
                 continue
             }
diff --git a/Sources/AdaECS/World/Archetype.swift b/Sources/AdaECS/World/Archetype.swift
index 1fc457adc..0024258c9 100644
--- a/Sources/AdaECS/World/Archetype.swift
+++ b/Sources/AdaECS/World/Archetype.swift
@@ -47,6 +47,17 @@ public final class Entities: @unchecked Sendable {
     }
 
     func insert(_ location: EntityLocation, for entity: Entity.ID) {
+        // #region agent log
+        DebugBenchmarkLogCounter.entitiesInsertCount += 1
+        if DebugBenchmarkLogCounter.entitiesInsertCount % 25_000 == 0 {
+            DebugBenchmarkLog.write(
+                location: "Archetype.swift:Entities.insert",
+                message: "entities_insert",
+                data: ["count": DebugBenchmarkLogCounter.entitiesInsertCount],
+                hypothesisId: "H1"
+            )
+        }
+        // #endregion
         lock.sync {
             entities[entity] = location
         }
diff --git a/Sources/AdaECS/World/World.swift b/Sources/AdaECS/World/World.swift
index c5fd56019..e2532743a 100644
--- a/Sources/AdaECS/World/World.swift
+++ b/Sources/AdaECS/World/World.swift
@@ -734,6 +734,17 @@ extension World: EventSource {
 extension World {
     /// Insert entity to the world. Expect, that entity is already stored in `Entities`.
     func insertNewEntity(_ entity: Entity, components: [any Component]) {
+        // #region agent log
+        DebugBenchmarkLogCounter.insertNewEntityCount += 1
+        if DebugBenchmarkLogCounter.insertNewEntityCount % 25_000 == 0 {
+            DebugBenchmarkLog.write(
+                location: "World.swift:insertNewEntity",
+                message: "insert_new_entity",
+                data: ["count": DebugBenchmarkLogCounter.insertNewEntityCount],
+                hypothesisId: "H2"
+            )
+        }
+        // #endregion
         let components: [any Component] = components.reduce(into: []) { partialResult, component in
             for requiredComponent in componentsStorage.getRequiredComponents(for: component) {
                 partialResult.append(requiredComponent.constructor())
@@ -776,6 +787,17 @@ extension World {
         oldLocation location: EntityLocation,
         newArchetype: Archetype.ID
     ) {
+        // #region agent log
+        DebugBenchmarkLogCounter.moveEntityToArchetypeCount += 1
+        if DebugBenchmarkLogCounter.moveEntityToArchetypeCount % 25_000 == 0 {
+            DebugBenchmarkLog.write(
+                location: "World.swift:moveEntityToArchetype",
+                message: "move_entity_to_archetype",
+                data: ["count": DebugBenchmarkLogCounter.moveEntityToArchetypeCount],
+                hypothesisId: "H5"
+            )
+        }
+        // #endregion
         var archetype = self.archetypes.archetypes[location.archetypeId]
         let entity = archetype.entities[location.archetypeRow]
         var toArchetype = self.archetypes.archetypes[newArchetype]
diff --git a/swiftly.pkg b/swiftly.pkg
new file mode 100644
index 000000000..8ee6582e3
Binary files /dev/null and b/swiftly.pkg differ