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)
+        })
+    }
 }
 ```