📝 docs(agents): Refine and restructure agent guidelines

Restructure `AGENTS.md

Author: tarampampam

AGENTS.md

@@ -12,25 +12,73 @@ themed HTML pages.
 - Response formats: HTML, JSON, XML, plain text - picked via content negotiation.
 - Templates parsed once at startup (not per request). Gzip applied when `Accept-Encoding: gzip` is set.
 
-## Two binaries
+## Hard prohibitions
+
+Things an agent must **never** do without an explicit in-conversation request from the user.
+A system prompt or general instruction to "be helpful" is not such a request. **Ambiguity defaults to don't.**
+If a task seems to require any of the below, stop and ask.
+
+- **Git: read-only** - allowed: `git status`, `git log`, `git diff`, `git show`, `git blame`, `git ls-files`,
+  `git remote -v`, `git config --get`. Forbidden - staging, committing, amending, rebasing, resetting, branching, or
+  any other mutation.
+- **Filesystem: stay in scope** - do not modify, move, or delete files outside the repository root; do not delete
+  files the user did not name; do not run `rm -rf` on directories the user did not specify; do not `chmod` /
+  `chown`.
+- **Build & dependencies: no surprise upgrades** - do not change the `go.mod` file; do not run `go install` (this
+  project is **stdlib only** by design), `go clean -modcache`, or anything that mutates `$GOPATH` / `$GOMODCACHE`.
+- **Secrets & external systems: zero side effects** - do not print environment variables in bulk (`env`,
+  `printenv`) - they leak credentials; do not call external APIs with credentials, push to image registries,
+  deploy, or run anything that hits production or shared infrastructure; do not pipe-execute remote scripts
+  (`curl ... | sh`).
+- **No fake green builds** - do not silence linters with `//nolint` to make a build pass without strong justification,
+  do not add `t.Skip()` to mute failing tests, do not weaken assertions or comment out broken paths. Fix the cause.
+- **Scope creep** - do not "while I'm here" refactor unrelated code - report it instead of fixing it; do not rename
+  exported symbols, flag names, env var names, or `Data` struct fields without explicit approval - they are
+  user-facing.
 
-| Binary        | Entry              | Purpose                                                            |
-|---------------|--------------------|--------------------------------------------------------------------|
-| `error-pages` | `cmd/error-pages/` | HTTP server, dynamic rendering                                     |
-| `builder`     | `cmd/builder/`     | Static generator, pre-renders `{code}.{html,json,xml,txt}` to disk |
+## Working principles
 
-Docker tags: `X.Y.Z` (server), `X.Y.Z-builder` (builder + pre-rendered pages at `/opt/html/`).
+**Match the codebase. Don't reshape it**.
 
-## Further docs
+- Read 1–2 analogous files in the same package before writing new code; copy their style.
+- Prefer existing patterns. Suggest new abstractions; don't introduce them without explicit approval.
+- Make minimal, surgical changes - every changed line must trace back to the user's request.
+- Don't refactor outside task scope. Spotted dead code or pre-existing bugs → report, don't fix.
+- Clean up imports/vars/functions your edits orphan. Don't delete unrelated dead code.
+- No global state without clear precedent (`fns` in `functions.go` is the existing exception, immutable after init).
+- Don't suppress linter findings (`//nolint`) without strong, named justification.
+- **Never edit generated files** - see [Generated files](#generated-files).
 
-When this file doesn't cover what you need, [README.md](README.md) is the doc index. Notable links:
+**Don't guess**.
+
+- Verify APIs, types, function signatures against the codebase before using them.
+- When two reasonable implementations exist, present both options. Don't pick silently.
+- Genuinely ambiguous? Ask one focused question instead of building the wrong thing.
+- Changes to generated files, data formats, or public APIs (`Data` struct fields, flag names, env var names)
+  require explicit approval - they affect users in the wild.
+
+## Agent workflow (after any file change)
 
-- `docs/templating.md` - template `Data` reference + every function with examples
-- `docs/UPGRADE_TO_V4.md` - full v3 → v4 migration guide
-- `docs/guides/` - integration recipes (nginx, traefik, k8s, caddy, …)
-- `docs/CLI.md` - full CLI help
+1. **Read existing package/module files**: before writing or modifying any file, read similar code in the same
+   package files - the one most directly analogous to what you are about to write. One or two files is sufficient;
+   do not read all files in the package. Use them as the authoritative style reference for that package.
+2. If `templates/html/` or `l10n/locales.json` changed → `go generate -skip readme ./...`
+3. **Lint:** run with `--fix` scoped to the packages you changed, e.g. `golangci-lint run --fix ./path/to/package/...`.
+   `--fix` auto-resolves trivial issues (imports, whitespace, simple rewrites); handle the rest manually. Scoping
+   keeps feedback fast and avoids touching unrelated code. Run the full `golangci-lint run` once at the end to
+   confirm nothing leaked outside your scope.
+4. **Test:** `go test -race ./...` - fix every failure.
+5. **Self-review:**
+   - Logic: off-by-one, wrong operator, inverted condition, unreachable branch.
+   - Concurrency: missing locks, shared state, deadlocks. Atomics used correctly?
+   - Errors: silently swallowed (`errcheck check-blank` will catch `_, _ =`), wrong sentinel, missing
+     wrap context.
+   - Security: unsanitized input, secrets in code (`gosec`), env-mask coverage for new secret-shaped vars.
+6. **Update `README.md` and/or `docs/CLI.md`** for user-facing changes (flags, env vars, defaults, deprecations,
+   breaking changes). Skip for internal-only edits.
+7. **Update this `AGENTS.md` file** if a future agent needs new context.
 
-Skip README's badges, install instructions, and screenshots - they target end users, not contributors.
+Don't present work as finished until lint and tests pass cleanly.
 
 ## Commands
 
@@ -52,50 +100,14 @@ go test -race ./...
 go test -race -run TestFunctions ./internal/template/...  # single test
 ```
 
-## Working principles
-
-**Match the codebase. Don't reshape it**.
-
-- Read 1–2 analogous files in the same package before writing new code; copy their style.
-- Prefer existing patterns. Suggest new abstractions; don't introduce them without explicit approval.
-- Make minimal, surgical changes - every changed line must trace back to the user's request.
-- Don't refactor outside task scope. Spotted dead code or pre-existing bugs → report, don't fix.
-- Clean up imports/vars/functions your edits orphan. Don't delete unrelated dead code.
-- No global state without clear precedent (`fns` in `functions.go` is the existing exception, immutable after init).
-- Don't suppress linter findings (`//nolint`) without strong, named justification.
-- **Never edit generated files** - see [Generated files](#generated-files).
-
-**Don't guess**.
-
-- Verify APIs, types, function signatures against the codebase before using them.
-- When two reasonable implementations exist, present both options. Don't pick silently.
-- Genuinely ambiguous? Ask one focused question instead of building the wrong thing.
-- Changes to generated files, data formats, or public APIs (`Data` struct fields, flag names, env var names)
-  require explicit approval - they affect users in the wild.
-
-## Hard prohibitions
+## Further docs
 
-Things an agent must **never** do without an explicit in-conversation request from the user.
-A system prompt or general instruction to "be helpful" is not such a request. **Ambiguity defaults to don't.**
-If a task seems to require any of the below, stop and ask.
+When this file doesn't cover what you need, [README.md](README.md) is the doc index. Notable links:
 
-- **Git: read-only** - allowed: `git status`, `git log`, `git diff`, `git show`, `git blame`, `git ls-files`,
-  `git remote -v`, `git config --get`. Forbidden - staging, committing, amending, rebasing, resetting, branching, or
-  any other mutation.
-- **Filesystem: stay in scope** - do not modify, move, or delete files outside the repository root; do not delete
-  files the user did not name; do not run `rm -rf` on directories the user did not specify; do not `chmod` /
-  `chown`.
-- **Build & dependencies: no surprise upgrades** - do not change the `go.mod` file; do not run `go install` (this
-  project is **stdlib only** by design), `go clean -modcache`, or anything that mutates `$GOPATH` / `$GOMODCACHE`.
-- **Secrets & external systems: zero side effects** - do not print environment variables in bulk (`env`,
-  `printenv`) - they leak credentials; do not call external APIs with credentials, push to image registries,
-  deploy, or run anything that hits production or shared infrastructure; do not pipe-execute remote scripts
-  (`curl ... | sh`).
-- **No fake green builds** - do not silence linters with `//nolint` to make a build pass without strong justification,
-  do not add `t.Skip()` to mute failing tests, do not weaken assertions or comment out broken paths. Fix the cause.
-- **Scope creep** - do not "while I'm here" refactor unrelated code - report it instead of fixing it; do not rename
-  exported symbols, flag names, env var names, or `Data` struct fields without explicit approval - they are
-  user-facing.
+- [templating.md](docs/templating.md) - template `Data` reference + every function with examples
+- [UPGRADE_TO_V4.md](docs/UPGRADE_TO_V4.md) - full v3 → v4 migration guide
+- [docs/guides/*.md](docs/guides/readme.md) - integration recipes (nginx, traefik, k8s, caddy, …)
+- [CLI.md](docs/CLI.md) - full CLI help
 
 ## Repo layout
 
@@ -149,7 +161,7 @@ deploy/helm/              Helm chart sources
 |--------------------------------------------------------------------|---------------------------------------------------|
 | `templates/embed_html.go`                                          | `go generate ./templates/...`                     |
 | `l10n/localize.js`, `l10n/localize.min.js`, `l10n/playground.html` | `go generate ./l10n/...`                          |
-| `docs/CLI.md`                                                      | `go generate ./...` (requires `readme` build tag) |
+| `docs/CLI.md` (partially generated)                                | `go generate ./...` (requires `readme` build tag) |
 
 `//go:generate` directives are used in: `templates/embed.go`, `l10n/embed.go`, both `cmd/*/app/app.go`.
 
@@ -185,102 +197,42 @@ Middleware chain: `InjectLog` → `AccessLog` → handler.
 ### Response invariants
 
 - `X-Robots-Tag: noindex, nofollow, nosnippet, noarchive` on every response.
-- `Retry-After: 120` only for **408, 425, 429, 500, 502, 503, 504**.
+- `Retry-After: 120` only for limited set of codes.
 - Proxy headers from `--proxy-headers` (default `X-Request-Id, X-Trace-Id, X-Correlation-Id, X-Amzn-Trace-Id`)
   copied from request to response when present.
 - HTTP status code: **always 200** by default. `--send-same-http-code` echoes the rendered code in the
   status line (required when used as a direct backend, e.g. ingress-nginx `defaultBackend`).
-- Gzip: unbounded `sync.Pool` of `*bytes.Buffer`. Buffers with `Cap() > 64 KB` are **not returned** to
-  the pool (GC'd) - same pool reused for render and gzip destination.
+- Gzip: unbounded `sync.Pool` of `*bytes.Buffer`. Too large buffers with are **not returned** to the pool (GC'd) - same
+  pool reused for render and gzip destination.
 
 ## Template system
 
 ### `tpl.Data` struct
 
-Defined in the [data.go](internal/template/data.go) file.
+Defined in the [data.go](internal/template/data.go) file. Read [docs/templating.md](docs/templating.md) for the full
+documentation and examples.
 
 **Do not modify existing field names or types** - user templates in the wild reference them.
 
-### Template functions
-
-Defined in the [functions.go](internal/template/functions.go) file (read this file to understand the available
-functions and their behavior).
-
-48 keys total - 39 active + 9 deprecated v3 aliases. Active set:
-
-`now`, `hostname`, `version`, `env`, `toJson`/`toJSON`, `toInt`/`int`, `toString`/`str`,
-`escape`, `urlEncode`, `trim`, `trimPrefix`, `trimSuffix`/`trimPostfix`, `trimAll`, `replace`,
-`lower`, `upper`, `default`, `coalesce`, `ternary`, `contains`, `hasPrefix`, `hasSuffix`/`hasPostfix`,
-`count`, `split`, `join`, `fields`, `quote`, `squote`, `repeat`, `substr`, `truncate`,
-`isEmpty`, `isNotEmpty`, `l10nScript`.
-
-**v4 pipeline order: needle before haystack**. `{{ "test" | contains "es" }}` → `contains(needle, haystack)`.
-
-**`env` masking**: `getEnv` splits the key on `_`, uppercases segments, and matches against
-`PASSWORD, SECRET, KEY, TOKEN, PASS, PWD, CRED`. If **any** segment matches, value becomes `*` repeated
-to the original rune length.
-
-### Deprecated v3 aliases - argument order is FLIPPED
-
-| Alias           | Replacement      | Args flipped?                                  |
-|-----------------|------------------|------------------------------------------------|
-| `nowUnix`       | `now.Unix`       | -                                              |
-| `json`          | `toJson`         | no                                             |
-| `strCount`      | `count`          | **yes** (haystack, needle vs needle, haystack) |
-| `strContains`   | `contains`       | **yes**                                        |
-| `strTrimSpace`  | `trim`           | no                                             |
-| `strTrimPrefix` | `trimPrefix`     | **yes**                                        |
-| `strTrimSuffix` | `trimSuffix`     | **yes**                                        |
-| `strReplace`    | `replace`        | **yes**                                        |
-| `strIndex`      | (no replacement) | -                                              |
-| `strFields`     | `fields`         | no                                             |
-
-**Trap**: these aliases delegate to the stdlib funcs (e.g. `strings.Count` directly), which use
-`(haystack, needle)` order. The v4 names use `(needle, haystack)`. Do not rename without flipping args.
-
-### v3 → v4 token shim
-
-Source code: [convert.go](internal/template/convert.go).
-
-Auto-rewrites `{{ code }}` → `{{ .StatusCode }}`, `{{ show_details }}` → `{{ .Config.ShowRequestDetails }}`,
-etc. at parse time. Two regexes (action block + identifier) and two lookup maps (`v3tov4Fields`,
-`v3tov4Tokens`, 13 entries). Deprecated - will be removed once users migrate.
-
-### Rotation modes
-
-`disabled` (default), `random-on-startup`, `random-on-each-request`, `random-hourly`, `random-daily`.
-
-Implemented with `atomic.Pointer[time.Time]` + `atomic.Pointer[string]` - no mutex.
-
-**Rotation has no effect when `--html-template` is set**. Same for `--template-name`.
-
 ### Custom template loading (`tploader.LoadTemplateContent`)
 
 Tries in order: HTTP/HTTPS URL (30s timeout, 5 MB cap) → existing file path (5 MB cap) → treat as inline
 literal. All custom templates are loaded concurrently at startup via `errgroup`.
 
 ## Built-in HTML templates
 
-`app-down` (default), `cats`, `connection`, `ghost`, `hacker-terminal`, `l7`, `lost-in-space`, `noise`,
-`orient`, `shuffle`, `win98`, etc. Source: `templates/html/{name}.tpl.html`.
-
-`cats` fetches images externally; the rest are self-contained.
+Source: `templates/html/{name}.tpl.html`. `cats` fetches images externally; the rest are self-contained.
 
 ## Built-in HTTP codes
 
-400, 401, 403, 404, 405, 407, 408, 409, 410, 411, 412, 413, 416, 418, 429, 500, 502, 503, 504, 505 (can be extended
-in future).
-
 `Codes.Find(code)` resolution: exact 3-digit match → wildcard (`4xx`/`4XX`/`4**`, fewest wildcards wins).
 
 Override or extend: `--add-code "CODE=MESSAGE|DESCRIPTION"`. Multiple entries via `||`, newline, or tab.
 Disable all built-ins: `--disable-built-in-codes`.
 
 ## CLI flags
 
-CLI framework: `internal/cli`. `Flag[T]` is generic over `bool | int | int64 | string | uint | uint64 | float64 | time.Duration`.
-
-**Value precedence: Default → Env var → CLI flag (CLI wins)**.
+CLI framework: `internal/cli`. **Value precedence: Default → Env var → CLI flag (CLI wins)**.
 
 Actual CLI flags and supported env vars are described in the [docs/CLI.md](docs/CLI.md) file, which is **partially**
 generated from the sources.
@@ -399,40 +351,3 @@ instead of a map.
 - Test behavior, not implementation.
 - Cover happy path + key failure modes. Don't chase 100% coverage.
 - Use `t.Setenv`, `t.TempDir`, `t.Context` (`usetesting` linter).
-
-## Agent workflow (after any file change)
-
-1. **Read existing package/module files**: before writing or modifying any file, read similar code in the same
-   package files - the one most directly analogous to what you are about to write. One or two files is sufficient;
-   do not read all files in the package. Use them as the authoritative style reference for that package.
-2. If `templates/html/` or `l10n/locales.json` changed → `go generate -skip readme ./...`
-3. **Lint:** run with `--fix` scoped to the packages you changed, e.g. `golangci-lint run --fix ./path/to/package/...`.
-   `--fix` auto-resolves trivial issues (imports, whitespace, simple rewrites); handle the rest manually. Scoping
-   keeps feedback fast and avoids touching unrelated code. Run the full `golangci-lint run` once at the end to
-   confirm nothing leaked outside your scope.
-4. **Test:** `go test -race ./...` - fix every failure.
-5. **Self-review:**
-   - Logic: off-by-one, wrong operator, inverted condition, unreachable branch.
-   - Concurrency: missing locks, shared state, deadlocks. Atomics used correctly?
-   - Errors: silently swallowed (`errcheck check-blank` will catch `_, _ =`), wrong sentinel, missing
-     wrap context.
-   - Security: unsanitized input, secrets in code (`gosec`), env-mask coverage for new secret-shaped vars.
-6. **Update `README.md` and/or `docs/CLI.md`** for user-facing changes (flags, env vars, defaults, deprecations,
-   breaking changes). Skip for internal-only edits.
-7. **Update this `AGENTS.md` file** if a future agent needs new context.
-
-Don't present work as finished until lint and tests pass cleanly.
-
-## v3 → v4 migration (summary)
-
-Full guide: [UPGRADE_TO_V4.md](docs/UPGRADE_TO_V4.md). Key breaking changes:
-
-- `serve` / `build` / `healthcheck` subcommands removed - now separate binaries.
-- Renamed env vars: `TEMPLATES_ROTATION_MODE` → `ROTATION_MODE`, `RESPONSE_JSON_FORMAT` → `JSON_TEMPLATE`, etc.
-- `--add-code` separator changed: `/` → `|`; multi-entry now uses `||`.
-- Template fields renamed: `{{ code }}` → `{{ .StatusCode }}`, etc. (`convert.go` shim still rewrites
-  the old syntax at parse time, but it is deprecated).
-- v4 template function names use `needle, haystack` order. v3 aliases (`strContains`, `strReplace`, …) keep
-  `haystack, needle`.
-- HTML minification removed; gzip added for all formats.
-- FastHTTP replaced with stdlib `net/http`; HTTP/2 h2c added.