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.
+- correct obvious grammatical and style errors in existing commentaries met in changed files.
 
 ---
 
@@ -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,
@@ -792,14 +785,14 @@ Preferred:
 
 ```go
 func ParsePort(s string) (int, error) {
-	port, err := strconv.Atoi(s)
-	if err != nil {
-		return 0, fmt.Errorf("parse port %q: %w", s, err)
-	}
-	if port < 1 || port > 65535 {
-		return 0, fmt.Errorf("parse port %q: out of range", s)
-	}
-	return port, nil
+    port, err := strconv.Atoi(s)
+    if err != nil {
+        return 0, fmt.Errorf("parse port %q: %w", s, err)
+    }
+    if port < 1 || port > 65535 {
+        return 0, fmt.Errorf("parse port %q: out of range", s)
+    }
+    return port, nil
 }
 ```
 
@@ -807,8 +800,8 @@ Avoid:
 
 ```go
 func ParsePort(s string) (int, error) {
-	i, _ := strconv.Atoi(s)
-	return i, nil
+    i, _ := strconv.Atoi(s)
+    return i, nil
 }
 ```
 
@@ -818,10 +811,10 @@ Preferred:
 
 ```go
 func (s *Service) Fetch(ctx context.Context, id string) (*Item, error) {
-	if err := ctx.Err(); err != nil {
-		return nil, err
-	}
-	return s.repo.Fetch(ctx, id)
+    if err := ctx.Err(); err != nil {
+        return nil, err
+    }
+    return s.repo.Fetch(ctx, id)
 }
 ```
 
@@ -829,7 +822,7 @@ Avoid:
 
 ```go
 func (s *Service) Fetch(id string) (*Item, error) {
-	return s.repo.Fetch(context.Background(), id)
+    return s.repo.Fetch(context.Background(), id)
 }
 ```
 
@@ -839,34 +832,34 @@ Preferred:
 
 ```go
 func TestParsePort(t *testing.T) {
-	t.Parallel()
+    t.Parallel()
 
-	tests := []struct {
-		name    string
-		input   string
-		want    int
-		wantErr bool
-	}{
-		{name: "valid", input: "8080", want: 8080},
-		{name: "non-numeric", input: "abc", wantErr: true},
-		{name: "out of range", input: "70000", wantErr: true},
-	}
+    tests := []struct {
+        name    string
+        input   string
+        want    int
+        wantErr bool
+    }{
+        {name: "valid", input: "8080", want: 8080},
+        {name: "non-numeric", input: "abc", wantErr: true},
+        {name: "out of range", input: "70000", wantErr: true},
+    }
 
-	for _, tt := range tests {
-		tt := tt
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
+    for _, tt := range tests {
+        tt := tt
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel()
 
-			got, err := ParsePort(tt.input)
-			if tt.wantErr {
-				require.Error(t, err)
-				return
-			}
+            got, err := ParsePort(tt.input)
+            if tt.wantErr {
+                require.Error(t, err)
+                return
+            }
 
-			require.NoError(t, err)
-			assert.Equal(t, tt.want, got)
-		})
-	}
+            require.NoError(t, err)
+            assert.Equal(t, tt.want, got)
+        })
+    }
 }
 ```
 

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.