docs: update readme and agents

AGENTS.md

@@ -1,12 +1,5 @@
 # AGENTS.md
 
-> This file defines how Codex and other coding agents should operate in this repository.
-> It is intentionally strict, verbose, and easy to trim down.
-> If any instruction here conflicts with an explicit user request in the chat, the user request wins.
-> If any instruction here conflicts with a deeper repository-local instruction in a subdirectory `AGENTS.md`, the deeper file wins for files inside that subtree.
-
----
-
 ## 1. Purpose
 
 This repository is developed primarily in Go.
@@ -71,12 +64,11 @@ Unless the user asks otherwise, the agent should:
 
 Unless the user asks otherwise, the agent should:
 
-- supply added packages, types, funcs, consts and vars with a commentaries explaining its purpose and behavior,
+- supply added packages, types, funcs, consts and vars with a comprehensive comments explaining its purpose and behavior,
 - supply public functions with a more comprehensive commentary and supplemental funcs with more concise comments,
-- provide comments respecting the Go Doc Comments syntax,
+- provide comments respecting the Go Doc Comments syntax: use strict parameters names inside human-friendly sentences,
 - provide comments only in English language,
-- translate any non-English commetraries met in existing code,
+- correct obvious grammatical and style errors in existing commentaries met in changed files.
-- correct obvious grammatical and style errors in existing commentaries.
 
 ---
 
@@ -173,6 +165,7 @@ If the repository does not make this obvious, assume modern stable Go and avoid
 
 The agent should prefer:
 
+- target Go version language idioms and syntax improvements,
 - simple package APIs,
 - concrete types when interfaces are not needed,
 - small interfaces defined by consumers,

README.md

@@ -1 +1,34 @@
-# galaxy-game
+# Galaxy
+
+Galaxy is a turn-based strategy game which took place in space.
+
+At the highest level Game has a Backend service and an UI Client.
+
+## Backend service
+
+Backend service is presented by several "microservices" with a different set of responsibilities.
+
+- AuthN Proxy Service: handles all incoming requests,
+  immediately rejects not-authenticated requests and passes authenticated request to the next service.
+
+- AuthZ Service: checks permissions avaliable to the authenticated user and passes request to the next service
+  if user is authorized to use specific game api.
+
+- Games Orchestrator Service:
+  - finds appropriate Game Server according to Client's request data,
+  - passes user's commands to the selected Game Server,
+  - reads response and bounces it back up to request chain to the Client,
+  - manages Game Server state for health monitoring and making next turn.
+
+- Game Servers: several instances of ongoing games with avaliable unprotected API ready to receive Player's and Administrator's commands.
+
+## UI Client
+
+UI Client is capable of:
+
+- Register a new player and login for an existing player using only e-mail and one-time codes,
+- Enlist to a new Game from available onboard Games list,
+- Request list of Games in which Player participating,
+- Request, store and display particular Game data,
+- Use push-like mechanism for receiving asynchronous updates from Server,
+- Offline mode when no internet connection is available or user desired to work offline.