docs: Update API surface and singleton architecture

docs/api-surface.md

@@ -86,6 +86,8 @@ public class World : IDisposable
     // --- Relationships ---
     public IReadOnlyCollection<Entity> GetSources<T>(Entity target)
         where T : struct, IRelationship;
+    public void ReorderSources<T>(Entity target, IReadOnlyList<Entity> ordered)
+        where T : struct, IRelationship;
 
     // --- Cleanup ---
     public void Dispose();
@@ -115,8 +117,12 @@ public static class WorldQueryExtensions
     // FindEntity — returns the first matching entity or Entity.Null.
     public static Entity FindEntity<T1>(
         this World world, Query<T1> query = default) where T1 : struct;
-    public static Entity FindEntity<T1, T2>(...) where T1 : struct where T2 : struct;
-    public static Entity FindEntity<T1, T2, T3>(...) where T1 : struct where T2 : struct where T3 : struct;
+    public static Entity FindEntity<T1, T2>(
+        this World world, Query<T1, T2> query = default)
+        where T1 : struct where T2 : struct;
+    public static Entity FindEntity<T1, T2, T3>(
+        this World world, Query<T1, T2, T3> query = default)
+        where T1 : struct where T2 : struct where T3 : struct;
 }
 ```
 

docs/architecture.md

@@ -288,8 +288,9 @@ serializable and executed deferred.
 **Context:** Singletons (global state like `Time`, `Config`, `InputState`) need
 a home in the ECS.
 
-**Decision:** Reserve entity ID `1` as the singleton entity. Provide
-convenience accessors (`SetSingleton<T>`, `GetSingleton<T>`). Exclude from
+**Decision:** Each singleton component type gets its own dedicated entity
+(allocated via `EntityAllocator`). Provide convenience accessors
+(`SetSingleton<T>`, `GetSingleton<T>`). Exclude all singleton entities from
 normal queries.
 
 **Rationale:**
@@ -300,11 +301,16 @@ normal queries.
   queries.
 - Simpler than a separate "resource" system (as in Bevy). One concept (entity +
   components) covers both entities and singletons.
+- Each singleton type having its own entity means `DestroyEntity` on a
+  singleton entity is a normal operation, and singletons can have multiple
+  component types attached without conflict.
 
 **Consequences:**
 
-- Entity ID `1` is permanently reserved.
-- `DestroyEntity` on the singleton entity is a no-op or throws.
+- A `Dictionary<Type, Entity>` maps each singleton component type to its
+  backing entity.
+- `IsSingletonEntity(Entity)` is checked during query iteration to exclude
+  singleton entities.
 
 ---