feat(matrix): land QA follow-ups and refresh docs

- harden Matrix onboarding/chat lifecycle after manual QA
- refresh README and Matrix docs to match current behavior
- add local ignores for runtime artifacts and include current planning/report docs

Closes #7
Closes #9
Closes #14

tests/adapter/matrix/test_dispatcher.py

@@ -3,7 +3,10 @@ from __future__ import annotations
 from types import SimpleNamespace
 from unittest.mock import AsyncMock
 
-from adapter.matrix.bot import MatrixBot, build_runtime
+from nio.api import RoomVisibility
+from nio.responses import SyncResponse
+
+from adapter.matrix.bot import MatrixBot, build_runtime, prepare_live_sync
 from adapter.matrix.handlers.auth import handle_invite
 from adapter.matrix.store import get_room_meta, get_user_meta, set_user_meta
 from core.protocol import IncomingCallback, IncomingCommand, OutgoingMessage
@@ -72,7 +75,12 @@ async def test_new_chat_creates_real_matrix_room_when_client_available():
     )
     result = await runtime.dispatcher.dispatch(new)
 
-    client.room_create.assert_awaited_once_with(name="Research", visibility="private", is_direct=False)
+    client.room_create.assert_awaited_once_with(
+        name="Research",
+        visibility=RoomVisibility.private,
+        is_direct=False,
+        invite=["u1"],
+    )
     client.room_put_state.assert_awaited_once()
     put_call = client.room_put_state.call_args
     assert put_call.kwargs.get("room_id") == "!space:example" or put_call.args[0] == "!space:example"
@@ -97,13 +105,27 @@ async def test_invite_event_creates_space_and_chat_room():
     room = SimpleNamespace(room_id="!dm:example.org", display_name="Alice")
     event = SimpleNamespace(sender="@alice:example.org", membership="invite")
 
-    await handle_invite(client, room, event, runtime.platform, runtime.store, runtime.auth_mgr)
+    await handle_invite(
+        client,
+        room,
+        event,
+        runtime.platform,
+        runtime.store,
+        runtime.auth_mgr,
+        runtime.chat_mgr,
+    )
 
     assert client.room_create.await_count == 2
     first_call = client.room_create.call_args_list[0]
     assert first_call.kwargs.get("space") is True or (
         len(first_call.args) > 0 and first_call.kwargs.get("space") is True
     )
+    assert first_call.kwargs.get("visibility") is RoomVisibility.private
+    assert first_call.kwargs.get("invite") == ["@alice:example.org"]
+    second_call = client.room_create.call_args_list[1]
+    assert second_call.kwargs.get("visibility") is RoomVisibility.private
+    assert second_call.kwargs.get("invite") == ["@alice:example.org"]
+    client.room_invite.assert_not_awaited()
 
     client.room_put_state.assert_awaited_once()
     put_state_call = client.room_put_state.call_args
@@ -137,8 +159,24 @@ async def test_invite_event_is_idempotent_per_user():
     room = SimpleNamespace(room_id="!dm:example.org", display_name="Alice")
     event = SimpleNamespace(sender="@alice:example.org", membership="invite")
 
-    await handle_invite(client, room, event, runtime.platform, runtime.store, runtime.auth_mgr)
-    await handle_invite(client, room, event, runtime.platform, runtime.store, runtime.auth_mgr)
+    await handle_invite(
+        client,
+        room,
+        event,
+        runtime.platform,
+        runtime.store,
+        runtime.auth_mgr,
+        runtime.chat_mgr,
+    )
+    await handle_invite(
+        client,
+        room,
+        event,
+        runtime.platform,
+        runtime.store,
+        runtime.auth_mgr,
+        runtime.chat_mgr,
+    )
 
     assert client.room_create.await_count == 2
 
@@ -179,3 +217,40 @@ async def test_mat11_settings_returns_dashboard():
     assert "Изменить" not in text
     assert "!connectors" not in text
     assert "!whoami" not in text
+
+
+async def test_mat12_help_returns_command_reference():
+    runtime = build_runtime(platform=MockPlatformClient())
+
+    result = await runtime.dispatcher.dispatch(
+        IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="help")
+    )
+
+    assert len(result) == 1
+    text = result[0].text
+    assert "!new" in text
+    assert "!rename" in text
+    assert "!archive" in text
+    assert "!settings" in text
+    assert "!yes" in text
+
+
+async def test_prepare_live_sync_returns_next_batch_from_bootstrap_sync():
+    client = SimpleNamespace(
+        sync=AsyncMock(
+            return_value=SyncResponse(
+                next_batch="s123",
+                rooms={},
+                device_key_count={},
+                device_list=SimpleNamespace(changed=[], left=[]),
+                to_device_events=[],
+                presence_events=[],
+                account_data_events=[],
+            )
+        )
+    )
+
+    since = await prepare_live_sync(client)
+
+    client.sync.assert_awaited_once_with(timeout=0, full_state=True)
+    assert since == "s123"