feat(agents): auto-register AgentConfig on first Ask (ApplyToPolicy now optional)

AskAsync/AskWithCallback register the built config with the global CoreAIAgent.Policy on
first use, so the newcomer flow is just Build() -> Ask*() with no manual
ApplyToPolicy(CoreAIAgent.Policy) step. Explicit ApplyToPolicy stays for custom policies and
up-front registration; re-applying is idempotent. A null policy now reports an uninitialized
lifetime scope instead of the misleading 'role not registered'.

Author: NeoXider

Assets/CoreAI/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+- **`AgentBuilder`: `ApplyToPolicy` is now optional.** `AskAsync`/`AskWithCallback` auto-register the built
+  `AgentConfig` with the global `CoreAIAgent.Policy` on first use, so the newcomer flow is just `Build()` →
+  `Ask*()` — no manual `ApplyToPolicy(CoreAIAgent.Policy)` step. The explicit call is still available for
+  custom policies or up-front registration; re-applying is idempotent. A null policy (uninitialized lifetime
+  scope) now fails with a clearer message than the old "role not registered".
+- **Benchmark: G7 no longer captures a scene screenshot.** The comprehensive-integration (Player/Gate/Key)
+  scenario photographed as an unreadable composite of overlapping primitives and floating world-space labels
+  that added nothing to the score. G6 (the free-build castle) is now the only hero image; G7 is graded purely
+  on world state + Lua consistency, like the other logic groups.
 - **Structured world spawning.** `world_command` `spawn`, `spawn_batch`, and `change` expose
   `worldPositionStays` (default `false`). Parented transforms are local by default; callers can pass `true`
   to preserve world space. The tool contract now recommends named `empty` roots and meaningful child

Assets/CoreAI/Docs/AGENT_BUILDER.md

@@ -339,13 +339,16 @@ Remember what the player bought using memory.")
     .WithChatHistory()
     .Build();
 
-// 2. Register (via global CoreAIAgent.Policy or your own policy)
-blacksmith.ApplyToPolicy(CoreAIAgent.Policy);
-
-// 3. Invoke (one line!)
+// 2. Invoke (one line!) — the first Ask auto-registers the agent with the global
+//    CoreAIAgent.Policy, so no manual registration step is needed.
 blacksmith.AskWithCallback("What do you have?");
 ```
 
+> **`ApplyToPolicy` is now optional.** `AskAsync`/`AskWithCallback` register the built config with the
+> global `CoreAIAgent.Policy` on first use, so newcomers can go straight from `Build()` to `Ask*()`.
+> Call `blacksmith.ApplyToPolicy(policy)` explicitly only when you target a **custom** `AgentMemoryPolicy`,
+> or want the role registered up front (e.g. before routing a task to it through the orchestrator directly).
+
 ### Recipe 2: Storyteller (chat only, no tools)
 
 ```csharp

Assets/CoreAI/Runtime/Core/Features/AgentMemory/AgentBuilder.cs

@@ -690,6 +690,12 @@ public sealed class AgentConfig
 
         /// <summary>
         /// Applies this built agent configuration to a mutable <see cref="AgentMemoryPolicy"/>.
+        /// <para>
+        /// For the common case you do NOT need to call this: <c>AskAsync</c>/<c>AskWithCallback</c>
+        /// auto-register the config with the global <see cref="CoreAIAgent.Policy"/> on first use.
+        /// Call this explicitly only when targeting a custom policy, or to register the role up front
+        /// (e.g. so the orchestrator can route to it before the first ask).
+        /// </para>
         /// </summary>
         public void ApplyToPolicy(AgentMemoryPolicy policy)
         {

Assets/CoreAI/Runtime/Core/Features/AgentMemory/AgentConfigExtensions.cs

@@ -40,10 +40,11 @@ public static Task<string> AskAsync(
             int priority = 0,
             CancellationToken cancellationToken = default)
         {
-            // Validate the agent config (role registration) before infrastructure state so an
-            // unregistered role fails with a clear "not registered" message regardless of whether
-            // the orchestrator happens to be initialized yet.
-            ValidateRoleRegistered(config);
+            // Make sure the role is known to the global policy before we run. For the common newcomer
+            // flow this AUTO-REGISTERS the built config, so `Build()` + `Ask*()` just works without an
+            // explicit `ApplyToPolicy(CoreAIAgent.Policy)` call. Done before the orchestrator null-check
+            // so a missing lifetime scope still surfaces its own clear message.
+            EnsureRoleRegistered(config);
 
             if (orchestrator == null)
             {
@@ -61,18 +62,28 @@ public static Task<string> AskAsync(
             }, cancellationToken);
         }
 
-        private static void ValidateRoleRegistered(AgentConfig config)
+        private static void EnsureRoleRegistered(AgentConfig config)
         {
             if (string.IsNullOrWhiteSpace(config?.RoleId))
             {
                 throw new InvalidOperationException("Role id is missing. Provide RoleId in AgentBuilder.");
             }
 
             AgentMemoryPolicy policy = CoreAIAgent.Policy;
-            if (policy == null || !policy.HasRole(config.RoleId))
+            if (policy == null)
             {
                 throw new InvalidOperationException(
-                    $"Role '{config.RoleId}' is not registered in CoreAIAgent.Policy. Call config.ApplyToPolicy(CoreAIAgent.Policy) (or Use BuildDetached() + explicit ApplyToPolicy()).");
+                    $"Cannot run agent '{config.RoleId}': CoreAIAgent.Policy is null. Initialize CoreAI first " +
+                    "(add CoreAILifetimeScope to the scene / run CoreAI setup) before asking an agent.");
+            }
+
+            // Convenience: register the built config with the global policy on first use, so newcomers
+            // do not have to call ApplyToPolicy(CoreAIAgent.Policy) by hand. Re-applying is idempotent;
+            // advanced users targeting a CUSTOM AgentMemoryPolicy still call ApplyToPolicy on that policy
+            // themselves (and, once registered here, this no-ops).
+            if (!policy.HasRole(config.RoleId))
+            {
+                config.ApplyToPolicy(policy);
             }
         }