gorig-cli 1.0.24 → 1.0.25

package/templates/skills/gorig-backend/references/capability-matrix.md

@@ -0,0 +1,37 @@
+# Capability Maturity Matrix
+
+This baseline reflects the locally inspected Gorig `master` from 2026-05-13. Re-evaluate it for the target project's resolved version.
+
+| Capability | Baseline | Verification source | Important boundary |
+|---|---|---|---|
+| `bootstrap.StartUp` and `serv` lifecycle | verified | `bootstrap/startup.go`, `serv/serv.go` | Service startup order uses map iteration; do not depend on ordering. |
+| HTTP server, routing, recovery, logging, CORS | verified | `httpx/serv.go`, middleware, HTTP tests, `references/auth-security.md` | `RegisterRouter` currently accepts `func(*gin.RouterGroup)`; CORS echoes request origin and must match the business security model; the built-in `/ping` payload has a timestamp formatting defect in the inspected baseline. |
+| `apix` binding, typed parameters, response handling | verified | `apix/params.go`, `apix/handle.go` | Typed getters and `HandleData` signatures are version-sensitive. |
+| Persistent CRUD module workflow | verified | `references/persistent-crud.md`, generated-project tests, live MySQL verification | Supports only MySQL and MongoDB in the verified workflow; HTTP is an optional adapter, not required for service-level CRUD. MongoDB effect verification still requires reachable development infrastructure. |
+| MySQL and MongoDB adapters | verified | `domainx` adapters and `test/dx_test.go` | Requires external services and matching configuration. |
+| Baseline `domainx/dx` CRUD query facade | verified | `domainx/dx/dx.go`, generated CRUD tests, real consumers | Some operations require an ID or non-empty matches as a safety guard. |
+| Advanced `domainx/dx` access | verified | `references/advanced-data-access.md`, `domainx/dx/dx.go`, compile fixture | External database behavior for aggregates, geo queries, indexes, escape hatches, and transactions must be integration-tested per backend. |
+| Memory, JSON, and SQLite cache | verified | `references/cache.md`, local cache behavior fixture, `cache/` source | Local backends do not prove Redis or cross-process behavior. |
+| Redis cache | source-verified | `cache/cache.redis.go`, `test/cache_test.go`, `references/cache.md` | Reads `redis.addr`, `redis.password`, and `redis.db`; runtime behavior requires configured Redis infrastructure before it is claimed in a delivery. |
+| Multi-level cache and singleflight | verified | `cache/cache.go`, local behavior fixture | Loader and invalidation behavior must be tested per value type. |
+| `cronx.AddCronTask` | verified | `references/scheduled-tasks.md`, `cronx/cron.go`, local fixture | Uses second-level cron expressions and optional timeout. |
+| `cronx.AddDelayTask`, `AddOnceTask` | verified | `references/scheduled-tasks.md`, `cronx/cron.go`, local fixture | Delay/once jobs run once and start cron internally. |
+| `cronx.AddEveryTask` | verified | `cronx/cron.go`, local fixture, Gorig `92c28b5` | Fixed interval helper delegates to `AddCronTask`; require commit `92c28b5` or equivalent in the target version. |
+| `cronx` persistent delay/once tasks | source-verified | `cronx/persist.go`, `test/cron_persist_test.go`, local fixture | Requires Gorig `0af68e8` or later plus configured Redis. Local validation covers handler/payload errors; runtime persistence requires Redis integration. |
+| Local `messagex` | verified | `references/messaging.md`, `mid/messagex/`, local fixture | Process-local only. Verify lifecycle and unsubscribe behavior per use case. |
+| Redis `messagex` | source-verified | `references/messaging.md`, `mid/messagex/`, `test/message_test.go` | Requires configured Redis integration before runtime behavior is claimed. |
+| Sequential messages, retry, local DLQ delivery | verified | `broker.simple.go`, local fixture | DLQ applies to sequential subscribers. Local broker cannot replay because it has no store. |
+| Redis DLQ replay | source-verified | `broker.simple.go`, Redis tests | Requires configured Redis integration before runtime replay behavior is claimed. |
+| RabbitMQ broker enum/path | unsupported | `mid/messagex/serv.go` | No broker implementation is constructed. |
+| SSE middleware and send helpers | verified | `httpx/ssex/`, `test/ssex_test.go` | Endpoint must be GET and must handle disconnects. |
+| Memory-backed JWT token manager and `SignDef` | verified | `mid/tokenx/`, `httpx/mid.sign.go`, local auth fixture, `references/auth-security.md` | Single-process default with local `./tokens.json` persistence; not cross-instance session storage. Test expiry, refresh, revoke, logout, and forbidden paths per app. |
+| Redis token manager and `SignRedis` | verified | `mid/tokenx/serv.go`, `mid/tokenx/redis.manager.go`, `test/tokenx_redis_test.go` | Implemented in local `master` commit `4dcf601` and expected in releases that include the Redis manager, such as planned `v0.0.53+`. Use it with Redis configuration. The real Redis integration test covers generate/reuse/clean/refresh/destroy/effective behavior and skips only when the environment lacks Redis. |
+| Role and attribute filtering | verified | `httpx.SignUserDef`, local auth fixture | Filters JWT `UserInfo` only; use service-layer authorization for database-owner or live-state rules. |
+| Debounce/rate protection | verified | `httpx/mid.debounce.go`, local auth/security fixture | Process-global state; whitelist API is spelled `DebouceAw`; repeated requests key by user id when token is valid, otherwise client IP. |
+| Request signing | unsupported | source search, `references/auth-security.md` | No verified generic request-signature middleware in the inspected baseline. Implement custom signing only after explicit security design confirmation. |
+| Outbound HTTP helpers | verified | `httpx/http.go`, local outbound fixture, `references/outbound-http.md` | Timeout support is helper-specific and `SetTimeOutTmp` is process-global; bad JSON/XML/status behavior differs by helper. |
+| Structured logging and trace context | verified | `utils/logger/`, logger tests | Propagate the request context instead of replacing it mid-request. |
+| Gorig OM integration | experimental | `gorig-om` | Separate repository and configuration; validate against its pinned Gorig version. |
+| Gorig Hub and Node | experimental | `gorig-hub`, `gorig-node` | Ecosystem components, not automatic core-framework behavior. |
+
+Update this matrix whenever source inspection or effect verification changes a status.

package/templates/skills/gorig-backend/references/configuration.md

@@ -0,0 +1,48 @@
+# Environment Configuration
+
+Gorig configuration uses Viper and loads a YAML file from `./_bin/` or `./`. The configuration name is selected before file loading.
+
+## Select an Environment
+
+Use the `GORIG_SYS_MODE` environment variable:
+
+```sh
+GORIG_SYS_MODE=local go run ./_cmd
+GORIG_SYS_MODE=dev go run ./_cmd
+GORIG_SYS_MODE=prod ./demo-api
+```
+
+The basic project generates:
+
+- `_bin/local.yaml`
+- `_bin/dev.yaml`
+- `_bin/prod.yaml`
+
+Each file declares its own `sys.mode` and HTTP address. The generated `/hello` response includes the loaded mode so the selection can be effect-tested.
+
+## Override Values
+
+Gorig uses the `GORIG` prefix and replaces dots with underscores. Examples:
+
+```sh
+GORIG_SYS_MODE=prod
+GORIG_API_REST_ADDR=:8080
+```
+
+Use environment variables or external secret management for passwords, private keys, tokens, and production endpoints. Do not put real secrets in generated or skill examples.
+
+## Working Directory Requirement
+
+Configuration paths are relative to the process working directory. Start the application from the project root unless the deployment explicitly arranges the configuration path.
+
+Go tests run with each package directory as the working directory. Shared external-style tests therefore keep a minimal configuration under `test/_bin/local.yaml`.
+
+## Validate Selection
+
+Do not validate configuration only by checking files. Start at least two environments and assert:
+
+- The process listens on the expected port.
+- `/hello` returns the expected `mode`.
+- Shutdown completes cleanly.
+
+If an environment variable overrides the port, report that override in the verification evidence.

package/templates/skills/gorig-backend/references/framework-api.md

@@ -0,0 +1,190 @@
+# Verified Framework API Baseline
+
+Use these snippets only after checking the target project's resolved Gorig version. They reflect the locally inspected `master` baseline and intentionally avoid incomplete scenarios that belong to later roadmap phases.
+
+## Application Entry
+
+`bootstrap.StartUp()` registers the built-in HTTP service. Do not register the same `httpx.Startup` lifecycle a second time unless the resolved framework version or a distinct server requires it.
+
+```go
+package main
+
+import "github.com/jom-io/gorig/bootstrap"
+
+import _ "example/domain"
+
+func main() {
+	bootstrap.StartUp()
+}
+```
+
+Import component packages for their documented `init()` registration only when the application uses them.
+
+## Route and Controller
+
+The inspected `RegisterRouter` callback receives `*gin.RouterGroup`.
+
+```go
+func init() {
+	httpx.RegisterRouter(func(root *gin.RouterGroup) {
+		group := root.Group("/hello")
+		group.GET("", getHello)
+	})
+}
+
+func getHello(ctx *gin.Context) {
+	defer apix.HandlePanic(ctx)
+	name, err := apix.GetParamType[string](ctx, "name", apix.NotForce, "world")
+	if err != nil {
+		return
+	}
+	result := map[string]string{"message": "hello " + name}
+	apix.HandleData(ctx, consts.CurdSelectFailCode, result, nil)
+}
+```
+
+Do not use obsolete examples that call typed parameter getters without `Force`/`NotForce`, discard their returned error, or call `HandleData` without a business error code.
+
+## Custom Lifecycle Service
+
+```go
+err := serv.RegisterService(serv.Service{
+	Code:     "WORKER",
+	Startup:  workerStartup,
+	Shutdown: workerShutdown,
+})
+if err != nil {
+	sys.Exit(err)
+}
+```
+
+Do not rely on relative startup order among registered services unless the target version provides ordering guarantees.
+
+## Model and dx
+
+For advanced filters, aggregates, projections, batch scans, indexes, direct-driver escape hatches, and transaction boundaries, read `advanced-data-access.md`.
+
+```go
+type Order struct {
+	UserID int64  `bson:"user_id" json:"user_id"`
+	Status string `bson:"status" json:"status"`
+}
+
+func (*Order) DConfig() (domainx.ConType, string, string) {
+	return domainx.Mongo, "main", "order"
+}
+
+func init() {
+	domainx.AutoMigrate(
+		func() domainx.ConTable {
+			return dx.On[Order](context.Background()).Complex()
+		},
+		domainx.CtIdx(domainx.Idx, "user_id", "status"),
+	)
+}
+```
+
+Common operations in the inspected version:
+
+```go
+id, err := dx.On(ctx, &order).Save()
+one, err := dx.On[Order](ctx).WithID(id).Get()
+list, err := dx.On[Order](ctx).Eq("status", status).Sort("id").Find()
+err = dx.On[Order](ctx).WithID(id).Update("status", "done")
+err = dx.On[Order](ctx).WithID(id).Delete()
+```
+
+Update and delete operations intentionally reject an empty ID/filter. Preserve those guards.
+
+The optional boolean on `Eq`, `Like`, and related methods means "ignore the framework's empty-value check." `true` therefore forces zero/empty values into the query; it does not skip the filter. Omit the boolean for ordinary optional filters.
+
+## Cache
+
+For cache-aside, invalidation, counters, queues, multi-level cache, singleflight, and source-of-truth guidance, read `cache.md`.
+
+```go
+memory := cache.New[Order](cache.Memory, time.Minute, time.Minute)
+jsonFile := cache.New[Order](cache.JSON, "orders")
+sqlite := cache.New[Order](cache.Sqlite, "orders")
+redis := cache.New[Order](cache.Redis)
+```
+
+Test local backends independently. Require explicit Redis configuration before claiming Redis behavior is verified.
+
+## Scheduled Task
+
+For task lifecycle, timeout, panic recovery, deduplication, delay/once jobs, and verification rules, read `scheduled-tasks.md`.
+
+```go
+cronx.AddCronTask("0 */5 * * * *", func(ctx context.Context) {
+	logger.Info(ctx, "scheduled sync")
+}, 30*time.Second)
+
+cronx.AddEveryTask(5*time.Minute, func(ctx context.Context) {
+	logger.Info(ctx, "interval sync")
+}, 30*time.Second)
+
+type DelayPayload struct {
+	OrderID int64 `json:"order_id"`
+}
+
+func (DelayPayload) PersistPayload() {}
+
+func handleDelay(ctx context.Context, payload DelayPayload) error {
+	logger.Info(ctx, "persistent delay task", zap.Int64("order_id", payload.OrderID))
+	return nil
+}
+
+_ = cronx.RegisterPersistTask(handleDelay)
+_, _ = cronx.AddPersistDelayTask(time.Minute, handleDelay, DelayPayload{OrderID: 1}, 30*time.Second)
+```
+
+Use `AddEveryTask` only when the target Gorig version includes commit `92c28b5` or an equivalent fix. Older versions can recursively lock during registration; use `AddCronTask("@every <interval>", ...)` directly on those versions.
+
+Use persistent delay/once tasks only when the target Gorig version includes commit `0af68e8` or an equivalent implementation and Redis is configured. Persistent handlers must be named functions, payloads must implement `PersistPayload`, and payloads must be JSON serializable.
+
+## Messaging
+
+For broker selection, sequential subscribers, retries, DLQ behavior, Redis integration, unsubscribe cleanup, and message-to-SSE composition, read `messaging.md`.
+
+```go
+broker := messagex.Ins(messagex.Local)
+subID, err := broker.RegisterTopic("order.created", func(msg *messagex.Message) *errors.Error {
+	return nil
+})
+if err == nil {
+	defer broker.UnRegisterTopic("order.created", subID)
+}
+broker.PublishNewMsg(ctx, "order.created", map[string]any{"order_id": id})
+```
+
+Use `messagex.Redis` only with configured Redis integration. RabbitMQ is unsupported in the inspected baseline.
+
+## SSE
+
+For streaming route structure, event/error payloads, long-lived streams, disconnect handling, and message-to-SSE composition, read `sse.md`.
+
+```go
+httpx.RegisterRouter(func(root *gin.RouterGroup) {
+	root.GET("/events", ssex.Mid(), func(ctx *gin.Context) {
+		_ = ssex.SendOK(ctx, "update", map[string]any{"ready": true})
+	})
+})
+```
+
+Handle send errors and client disconnects in long-lived streams.
+
+## Authentication Boundary
+
+`httpx.SignDef()` uses the memory-backed token manager. Verify generation, expiry, refresh, revocation, and persistence for the application before production use.
+
+Do not use `httpx.SignRedis()` against a version whose `tokenx.Redis` manager is unimplemented.
+
+## Logging
+
+```go
+logger.Info(ctx, "order created", zap.Int64("order_id", id))
+logger.Error(ctx, "save order failed", zap.Error(err))
+```
+
+Pass request context through every layer. Use `logger.NewCtx()` only when there is no request context, such as an independent background job.

package/templates/skills/gorig-backend/references/messaging.md

@@ -0,0 +1,143 @@
+# Messaging
+
+Use this reference when a task needs in-process pub/sub, Redis-backed messaging, sequential subscribers, retries, dead letter queues, replay, unsubscribe behavior, or message-to-SSE composition.
+
+Always inspect the target project's resolved Gorig source first. The examples below reflect the locally inspected Gorig `master` commit `35bbefb`.
+
+## Broker Choice
+
+Use `github.com/jom-io/gorig/mid/messagex`.
+
+```go
+localBroker := messagex.Ins(messagex.Local)
+redisBroker := messagex.Ins(messagex.Redis)
+```
+
+Supported in the inspected baseline:
+
+| Broker | Status | Notes |
+|---|---|---|
+| `messagex.Local` | verified | Process-local pub/sub. Good for in-process events and tests. |
+| `messagex.Redis` | source-verified | Uses Redis cache/list storage. Requires configured Redis before runtime behavior is claimed. |
+| `messagex.RabbitMQ` | unsupported | Enum exists, but no broker implementation is constructed. |
+
+Do not silently switch to Redis. Redis messaging requires `redis.addr`, `redis.password`, and `redis.db` or the corresponding `GORIG_REDIS_*` environment variables.
+
+## Publish and Subscribe
+
+Concurrent subscribers receive messages independently. Handler calls run asynchronously for non-sequential subscriptions.
+
+```go
+broker := messagex.Ins(messagex.Local)
+
+subID, err := broker.RegisterTopic("order.created", func(msg *messagex.Message) *errors.Error {
+    orderID := msg.GetValueInt64("order_id")
+    logger.Info(msg.Ctx, "order created event received", zap.Int64("order_id", orderID))
+    return nil
+})
+if err != nil {
+    return err
+}
+defer broker.UnRegisterTopic("order.created", subID)
+
+broker.PublishNewMsg(ctx, "order.created", map[string]any{
+    "order_id": id,
+})
+```
+
+`PublishNewMsg` converts struct and map content to `map[string]interface{}` and lowercases content keys. Use the typed getters when consuming:
+
+```go
+msg.GetValue("name")
+msg.GetValueStr("name")
+msg.GetValueInt64("order_id")
+msg.GetValueFloat64("amount")
+```
+
+## Sequential Consumption
+
+Use `RegisterTopicSeq` when a subscriber must process messages one at a time in publish order.
+
+```go
+subID, err := broker.RegisterTopicSeq("order.created", func(msg *messagex.Message) *errors.Error {
+    return rebuildProjection(msg.Ctx, msg.GetValueInt64("order_id"))
+}, messagex.WithMaxRetry(3), messagex.WithRetryIntervals(500*time.Millisecond))
+```
+
+Sequential behavior is per subscriber. Multiple subscribers still receive their own copy of each message.
+
+## Retry and DLQ
+
+Sequential subscribers can retry failed messages. When retries are exhausted, the message is sent to the configured DLQ topic.
+
+```go
+subID, err := broker.RegisterTopicSeq(
+    "order.project",
+    handler,
+    messagex.WithMaxRetry(2),
+    messagex.WithRetryIntervals(100*time.Millisecond, time.Second),
+    messagex.WithDLQTopic("order.project.dead"),
+)
+```
+
+Local broker behavior:
+
+- Retry is verified.
+- Failed messages can be published to a DLQ topic.
+- `ReplayDLQ` is not available because the local broker has no store; it returns `store not initialized for dlq replay`.
+
+Redis broker behavior:
+
+- Retry, delayed requeue, and replay use Redis storage.
+- `ReplayDLQ(topic, limit)` requeues messages from `topic + ".dlq"` unless a custom DLQ topic was configured.
+- Verify with disposable Redis before claiming replay behavior.
+
+## Unsubscribe and Cleanup
+
+Always keep the returned subscription ID and unregister when the subscriber is scoped to a test, lifecycle, or temporary workflow:
+
+```go
+subID, err := broker.RegisterTopic(topic, handler)
+if err != nil {
+    return err
+}
+defer broker.UnRegisterTopic(topic, subID)
+```
+
+Unsubscribe closes the subscriber channel and removes topic state when no subscribers remain. Do not publish to a topic from a goroutine that outlives its intended subscriber lifecycle unless that behavior is part of the design.
+
+## Message to SSE Composition
+
+For simple same-process streams, register a local topic subscriber inside the SSE handler and unregister it when the request context is done:
+
+```go
+func streamOrders(ctx *gin.Context) {
+    subID, err := messagex.Ins(messagex.Local).RegisterTopic("order.updated", func(msg *messagex.Message) *errors.Error {
+        if sendErr := ssex.SendOK(ctx, "order.updated", msg.Content); sendErr != nil {
+            return errors.Sys(sendErr.Error())
+        }
+        return nil
+    })
+    if err != nil {
+        _ = ssex.SendError(ctx, "order.updated", err.Error())
+        return
+    }
+    defer messagex.Ins(messagex.Local).UnRegisterTopic("order.updated", subID)
+
+    <-ctx.Request.Context().Done()
+}
+```
+
+This pattern holds a request open. Use it only for SSE routes and handle send errors as disconnect signals. For cross-process events, use Redis messaging after Redis integration is verified.
+
+## Verification Checklist
+
+- Compile against the target project's resolved Gorig version.
+- Verify local publish/consume for success payloads.
+- Verify multiple subscribers each receive each message.
+- Verify sequential subscribers preserve publish order.
+- Verify retry count and retry ordering.
+- Verify DLQ delivery for local broker or DLQ replay for Redis broker.
+- Verify unsubscribe prevents further delivery.
+- Verify Redis publish/consume, ordering, retry, DLQ, replay, and cleanup only against disposable or explicitly supplied Redis configuration.
+- Record RabbitMQ as unsupported unless the target version adds a real implementation.

package/templates/skills/gorig-backend/references/onboarding-files.md

@@ -0,0 +1,46 @@
+# Repository Onboarding
+
+Inspect only the files needed to build an accurate request path and lifecycle model.
+
+## Target Project First
+
+Locate:
+
+- `AGENTS.md` and repository instructions.
+- `go.mod`, `go.sum`, and `replace` directives.
+- Entry points such as `_cmd/main.go`, `_cmd/api/main.go`, or `simple/main.go`.
+- Environment files under `_bin/` and configuration access under `global/`.
+- Domain registration and blank imports.
+- Existing Router -> Controller -> Service -> Model/Domainx modules.
+- Existing tests, build scripts, deployment files, and documentation.
+
+Trace one complete existing behavior before proposing a new pattern.
+
+## Framework Files by Concern
+
+Read the resolved Gorig version, not an unrelated checkout.
+
+- Startup and lifecycle: `bootstrap/startup.go`, `serv/serv.go`.
+- HTTP server and routing: `httpx/serv.go`, `httpx/mid.*.go`.
+- Parameters and responses: `apix/params.go`, `apix/handle.go`, `apix/response/response.go`.
+- Data access: `domainx/`, `domainx/dx/dx.go`, relevant database adapter, and `test/dx_test.go`.
+- Cache: `cache/` and `test/cache_test.go`.
+- Scheduled tasks: `cronx/` and `test/cron_test.go`.
+- Messaging: `mid/messagex/` and `test/message_test.go`.
+- Authentication: `mid/tokenx/`, `httpx/mid.sign.go`, and relevant tests or real consumers.
+- Security middleware: `httpx/mid.cors.go`, `httpx/mid.debounce.go`, `httpx/mid.logger.go`, and response helpers for auth/rate-limit errors.
+- Outbound HTTP: `httpx/http.go` and any project-specific external API wrappers.
+- SSE: `httpx/ssex/` and `test/ssex_test.go`.
+- Configuration, errors, and logs: `utils/cofigure/`, `utils/errors/`, `utils/logger/`.
+
+## Reading Strategy
+
+1. Trace imports and `init()` registration from the entry point.
+2. Trace one HTTP request from route to response.
+3. Confirm parameter and response function signatures.
+4. Confirm context, error, and logging conventions.
+5. Confirm component startup and shutdown behavior.
+6. Confirm the behavior in tests or a real project.
+7. Reuse the target project's established architecture unless there is a clear reason to change it.
+
+If the project layout is unfamiliar, discover it with `rg --files` and package imports before asking the user.

package/templates/skills/gorig-backend/references/outbound-http.md

@@ -0,0 +1,162 @@
+# Outbound HTTP
+
+Use this reference when the backend must call another HTTP service, fetch remote data, post forms, send JSON/XML, forward headers, propagate context, enforce timeouts, handle bad responses, or fetch images.
+
+Always inspect the target project's resolved `httpx/http.go` before coding. The inspected API is convenient but not a complete production client abstraction.
+
+## Business Workflow
+
+Translate business language before choosing helpers:
+
+- "Call the partner API" means define the request, timeout, retry/idempotency expectation, headers, response mapping, and business error shown to callers.
+- "Forward the user's token" means use context-aware helpers only when forwarding `Authorization` is intended and safe.
+- "Do not hang the request" means use a per-call timeout and test it against a slow local server.
+- "Bad upstream response" means decide whether the caller sees a retryable error, fallback data, or a business failure.
+- "Fetch an image" means verify content type, size limits, and allowed hosts if the URL comes from users.
+
+For material outbound changes, confirm:
+
+```text
+Business goal:
+- <external effect or data needed>
+
+Upstream contract:
+- Method/path:
+- Request body/query:
+- Headers:
+- Expected success response:
+- Bad response behavior:
+- Timeout:
+
+Security:
+- Which user headers are forwarded:
+- Which secrets/config keys are required:
+- URL allowlist or SSRF boundary:
+
+Verification:
+- Local httptest server cases:
+- Timeout case:
+- Bad JSON/XML/status case:
+```
+
+## Supported Helpers
+
+The inspected source exposes:
+
+```go
+body, err := httpx.Get(url, map[string]string{"q": "abc"})
+body, err := httpx.GetHeader(url, params, map[string]string{"X-Trace-ID": traceID})
+data, err := httpx.GetMap(url, params)
+data, err := httpx.GetMapHeader(url, params, headers)
+
+body, err := httpx.PostForm(url, form)
+body, err := httpx.PostJSONResp(url, payload)
+body, err := httpx.PostJSONRespHeader(url, payload, headers)
+data, err := httpx.PostJSON(url, payload)
+data, err := httpx.PostJSONHeader(url, payload, headers)
+
+data, err := httpx.GetByCtx(ctx, url, map[string]interface{}{"id": id})
+data, err := httpx.PostJSONByCtx(ctx, url, payload)
+
+xmlBody, err := httpx.PostXML(url, map[string]string{"id": "1"})
+parsed, err := httpx.ParseXML[Resp](xmlBody)
+
+img, contentType, ext, err := httpx.FetchImage(url)
+```
+
+Known boundaries in inspected source:
+
+- `Get` and `PostForm` use package-level `http.Get`/`http.PostForm`, not the timeout-aware shared client.
+- `GetHeader`, `PostJSONResp`, and `PostJSONRespHeader` use the shared client.
+- `SetTimeOutTmp(duration)` mutates the package-level shared client temporarily; it is process-global and can affect concurrent calls.
+- `PostJSONResp` returns an error for non-200/non-201 status and includes the response body string.
+- `PostJSONRespHeader` does not reject non-2xx by itself in the inspected source.
+- `ParseJSON` returns nil for empty or invalid JSON after logging; callers must validate required fields.
+- `ParseXML` panics on invalid XML in the inspected source. Wrap or avoid it when upstream XML may be malformed.
+- `FetchImage` infers type from URL suffix and does not enforce response status, response content type, size, or host allowlist.
+
+## Context and Header Propagation
+
+For internal calls that intentionally forward the caller's token:
+
+```go
+result, err := httpx.PostJSONByCtx(ctx, upstreamURL, payload)
+```
+
+This forwards only `Authorization` in inspected source. If trace or tenant headers must propagate, build an explicit header map:
+
+```go
+headers := map[string]string{
+    "X-Request-ID": apix.GetTraceID(ctx),
+    "X-Tenant-ID": tenantID,
+}
+result, err := httpx.PostJSONHeader(upstreamURL, payload, headers)
+```
+
+Do not forward user tokens to third-party systems unless that is the explicit contract.
+
+## Timeout Pattern
+
+For helpers that use the shared client:
+
+```go
+httpx.SetTimeOutTmp(300 * time.Millisecond)
+resp, err := httpx.GetHeader(url, nil, nil)
+```
+
+Because the timeout is package-global, prefer a narrow call scope and avoid parallel tests that depend on different timeout values. For production-grade per-request cancellation, use a local `http.Client` and `http.NewRequestWithContext` after confirming this custom path with the user.
+
+## Error Mapping
+
+Keep outbound failure handling in the service layer:
+
+- network timeout or connection refused: return a retryable business error when appropriate;
+- non-success status: include safe upstream status and correlation id, not raw secrets or full upstream body;
+- invalid JSON/XML: return a parse error with enough context for support;
+- missing required fields: treat as bad upstream contract, not success with zero values;
+- image fetch failures: reject unsupported/oversized/untrusted URLs before download when user-supplied.
+
+## XML Boundary
+
+`PostXML` builds XML from simple string values and is suitable only for flat request bodies. For nested XML or signed XML, use typed `encoding/xml` structs and explicit tests.
+
+Wrap `ParseXML` if malformed XML is a normal upstream failure:
+
+```go
+func safeParseXML[T any](body string) (out *T, err *errors.Error) {
+    defer func() {
+        if r := recover(); r != nil {
+            err = errors.Sys("invalid upstream XML")
+        }
+    }()
+    return httpx.ParseXML[T](body)
+}
+```
+
+## Image Fetch Boundary
+
+Before fetching user-provided image URLs, define:
+
+- allowed schemes and hosts;
+- max response bytes;
+- accepted content types;
+- behavior for redirects;
+- storage location and malware scanning responsibility when relevant.
+
+Use the built-in `FetchImage` only for trusted internal or controlled fixture URLs unless these checks are added.
+
+## Verification Checklist
+
+Use a local `httptest.Server` or controlled local HTTP server. Cover:
+
+- GET query parameters;
+- form POST content type and body;
+- JSON POST request body and response mapping;
+- XML POST and parse success;
+- custom headers received by upstream;
+- `Authorization` forwarding through `GetByCtx` or `PostJSONByCtx` only when intended;
+- timeout against a slow handler;
+- connection or bad status error handling;
+- malformed JSON/XML response behavior;
+- image fetch returns bytes, content type, and extension for a controlled image URL;
+- no real secrets in URLs, headers, fixtures, or logs.