gorig-cli 1.0.24 → 1.0.25

package/templates/skills/gorig-backend/references/auth-security.md

@@ -0,0 +1,194 @@
+# Authentication and Security
+
+Use this reference when the request involves login, logout, protected routes, token refresh, user identity, roles, access filtering, CORS, debounce/rate protection, request signing, secrets, or sensitive logs.
+
+Always inspect the target project's resolved Gorig source first. Redis token manager is implemented in the current source line and is expected to be available in releases that include `mid/tokenx/redis.manager.go` such as the planned `v0.0.53+`. Local `master` commit `4dcf601` has a real Redis integration test in `test/tokenx_redis_test.go`; that test passes when Redis is configured and skips with `redis is not configured` when the environment is missing Redis.
+
+## Business Workflow
+
+Translate business language before coding:
+
+- "Login" means a route verifies credentials, creates a token, records it through the selected token manager, and returns only non-sensitive user data.
+- "Only logged-in users can access" means protected routes must use token middleware and service logic must read the injected user context, not trust a request body user id.
+- "Admin only" or "role-based access" means `SignUserDef` with `userInfo` filters when the required attributes are inside the token claims; use service-layer authorization when the rule depends on live database state.
+- "Logout" means the current token is destroyed and the same token no longer accesses protected routes.
+- "Refresh token" means the old token is eligible for refresh, a new token is generated, the manager swaps old to new, and the old token stops working.
+
+For a material auth change, present this confirmation plan before editing:
+
+```text
+Business goal:
+- <who can do what, and what logout/expiry should mean>
+
+Identity model:
+- User id source:
+- Token claims/userInfo:
+- Role or attribute rules:
+- Whether live database checks are required:
+
+Recommended design:
+- Token manager:
+- Protected routes:
+- Forbidden behavior:
+- Logout/refresh behavior:
+
+Security boundary:
+- Secret source:
+- Sensitive fields excluded from logs/responses:
+- Redis-token status for this Gorig version:
+
+Verification:
+- Login -> protected route -> logout:
+- Missing/malformed/expired/refreshed/revoked/forbidden token:
+- User context and trace context:
+```
+
+## Token Manager
+
+Memory token is the verified default for local and simple single-process flows:
+
+```go
+svc := tokenx.Get(tokenx.Jwt, tokenx.Memory)
+token, err := svc.Manager.GenerateAndRecord(ctx, userID, userInfo, 3600)
+```
+
+Important behavior:
+
+- `Generator.Generate(userID, userInfo, expireAt)` uses `expireAt` as seconds from now in the inspected source.
+- `Manager.GenerateAndRecord` may reuse an existing token for the same user id and same derived user type.
+- `Manager.Clean(userID)` revokes all tokens for the user.
+- `Manager.Destroy(token)` revokes one token.
+- Memory token state is process-local plus `./tokens.json` persistence in inspected versions; do not present it as cross-instance session storage.
+- In inspected versions, `Destroy(token)` deletes from memory but does not itself force an immediate `tokens.json` rewrite. Verify logout/revocation in the target app, especially for the last active token in a process.
+- Do not log raw tokens or full userInfo when it may include phone numbers, emails, roles not intended for clients, or other sensitive data.
+
+Redis token rules:
+
+- Confirm the target version includes `mid/tokenx/redis.manager.go` or an equivalent Redis manager implementation before using `httpx.SignRedis()` or `SignUserRedis()`.
+- For `v0.0.53+` or any project resolved to source containing the Redis manager, treat Redis token as an implemented and usable capability.
+- Check whether the target source includes `test/tokenx_redis_test.go` or equivalent integration coverage.
+- When Redis is configured, run `go test ./test -run TestRedisTokenManager -v` or the target project's equivalent as the runtime integration check.
+- When Redis is not configured and the test skips, report the missing Redis configuration and tell the user how to provide it; do not describe Redis token as unavailable or switch to memory unless the user accepts the single-process tradeoff.
+- The master integration test covers `GenerateAndRecord`, same-user/same-`userInfo` token reuse, old-token cleanup when userInfo changes, `Clean(userID)`, `Refresh`, `Destroy`, and `IsEffective`.
+- Never silently switch a user-requested Redis session design to memory token without explaining the restart/cross-process behavior difference.
+
+## Middleware
+
+Use memory middleware for simple local single-process flows. Use Redis middleware when the business needs Redis-backed token state and the target version includes the Redis token manager:
+
+```go
+group := root.Group("/account")
+group.GET("/me", httpx.SignDef(), me)
+group.GET("/admin", httpx.SignUserDef(map[string]interface{}{"role": "admin"}), admin)
+```
+
+Middleware expectations:
+
+- Missing `Authorization` header returns a token parameter error.
+- Header must be `Bearer <token>` and token length must pass the framework check.
+- Valid token sets `consts.TokenKey`, user id via `apix.SetUserID`, and userInfo via `apix.SetUserInfo`.
+- User id is also inserted into request context through `consts.UserIDKey`, so logger fields can include it when the same context is propagated.
+- `SignUserDef` filters against JWT `UserInfo`; it does not query the database.
+- A mismatched filter returns forbidden; use service-level checks for data-owner rules such as "only the order owner can update this order".
+
+## Minimal Login Flow
+
+Keep the first slice small:
+
+```text
+POST /auth/login
+- verify demo or real credentials in service
+- generate and record token
+- return token plus public user profile
+
+GET /auth/me
+- protected with SignDef
+- read user id and userInfo from apix
+
+POST /auth/logout
+- protected with SignDef
+- destroy current token from httpx.GetToken
+```
+
+When no user store exists yet, use an explicit demo account only in local fixtures and label it as non-production.
+
+## Refresh Flow
+
+Use the manager directly and test both old and new tokens:
+
+```go
+oldToken := httpx.GetToken(ctx)
+if !svc.Manager.IsMeetRefresh(oldToken) {
+    response.ErrorTokenRefreshFail(ctx)
+    return
+}
+newToken, err := svc.Generator.Generate(userID, userInfo, refreshSeconds)
+if err != nil || !svc.Manager.Refresh(oldToken, newToken) {
+    response.ErrorTokenRefreshFail(ctx)
+    return
+}
+```
+
+After refresh:
+
+- old token must fail protected routes;
+- new token must pass protected routes;
+- user context must still be present.
+
+## CORS
+
+The built-in HTTP service installs `httpx.CORS()` globally in inspected source. For direct router tests or custom servers, attach it explicitly.
+
+Verify:
+
+- `OPTIONS` preflight returns HTTP 204;
+- `Access-Control-Allow-Origin` echoes the request origin when present;
+- `Access-Control-Allow-Headers` includes `Authorization` and any custom allowed headers;
+- credentials are allowed only when this matches the business security model.
+
+Use `httpx.SetOtherAllowHeaders("X-Tenant-ID")` only for explicit header requirements.
+
+## Debounce and Rate Protection
+
+The built-in HTTP service installs `httpx.Debounce(200 * time.Millisecond)` in inspected source. For route-level behavior tests, attach `httpx.Debounce(duration)` directly.
+
+Behavior:
+
+- The key is path plus query for GET requests.
+- If a valid token is present, the key uses the token's user id.
+- Otherwise, the key uses client IP.
+- A repeated request within the duration returns HTTP 429.
+- `httpx.DebouceAw(path...)` whitelists exact paths. Preserve the misspelling because it is the inspected API name.
+- `httpx.DebounceDisable()` disables the global debounce switch for the process; use it cautiously in tests because it affects later tests.
+
+## Request Signing Boundary
+
+Do not invent request-signature support. If the business asks for "API signature" or "signed callbacks":
+
+1. Search the target source for a verified signing middleware/helper.
+2. If absent, propose a custom middleware with nonce, timestamp, body hash, shared secret, replay window, and tests.
+3. Require explicit confirmation because this is security-sensitive custom behavior.
+
+## Secret and Log Rules
+
+- Read JWT secrets from configuration or environment, never from hard-coded examples.
+- Use placeholder values such as `change-me-local-jwt-key`; never include real tokens, passwords, webhook URLs, or production hosts in fixtures.
+- Do not log `Authorization`, raw token strings, passwords, refresh secrets, or full outbound request bodies containing credentials.
+- Existing middleware may log headers; if protecting sensitive routes, inspect and adjust logging behavior before production use.
+- The inspected memory `Destroy` logs the raw token. Treat this as a production hardening item if framework behavior is unchanged in the target version.
+
+## Verification Checklist
+
+Tests must cover:
+
+- valid token reaches protected route;
+- missing header fails;
+- malformed `Authorization` fails;
+- expired JWT is tested through `IsNotExpired`/`IsEffective`, and protected-route behavior is tested for manager-expired or unrecorded tokens according to the resolved version;
+- refreshed token swaps old to new;
+- revoked/logout token fails;
+- forbidden role or attribute fails;
+- middleware writes `apix.GetUserID`, `apix.GetUserInfo`, request-context user id, and preserves trace context;
+- CORS preflight and allowed headers;
+- debounce repeated request and whitelisted path;
+- examples and fixtures contain no real secrets.

package/templates/skills/gorig-backend/references/business-scenarios.md

@@ -0,0 +1,155 @@
+# Business Scenario Workflow
+
+Use this reference when the user describes a business outcome instead of naming a Gorig component. This file is a workflow, not a rule catalog. Do not keep adding one-off mappings for every module or domain.
+
+The goal is to help the model reason from the user's business language to a small, confirmed backend plan using the target project's actual code and the verified Gorig capabilities.
+
+## Interaction Workflow
+
+When the user asks for a feature in ordinary language, do this before coding:
+
+1. Restate the business outcome.
+2. Inspect the existing project model, service, routes, docs, config, and tests that are likely related.
+3. Identify the workflow shape:
+   - trigger: user action, persisted data change, schedule, external callback, or stream request;
+   - wait/ordering: immediate, delayed, periodic, ordered, retryable, or one-shot;
+   - durability: may be lost on restart, must survive restart/deploy, or must be auditable;
+   - visibility: backend-only, API-visible, browser-real-time, or external-system-visible;
+   - consistency: best-effort, at-least-once, exactly-once expected by business, or idempotent enough;
+   - state owner: existing table/model, new field, new log table, cache, message payload, token/session manager, external service, or no persisted state;
+   - identity/security: anonymous, logged-in user, role/attribute restricted, owner-only, signed external callback, or system-to-system secret;
+   - outbound dependency: none, internal service, third-party API, user-provided URL, or webhook/callback.
+4. Generate a recommended design using Gorig capabilities already verified for the resolved version.
+5. Compare alternatives only when the business requirement has a real tradeoff, such as precision vs. infrastructure, synchronous vs. async, polling vs. streaming, or local vs. cross-process behavior.
+6. Recommend the smallest design that satisfies the stated business outcome.
+7. Separate current scope from future extensions.
+8. Ask only the blocking confirmation questions.
+9. Wait for explicit confirmation before editing code.
+
+## Gorig Capability Families
+
+Use these as ingredients during analysis. Do not expose them as choices the user must understand unless a tradeoff depends on them.
+
+- Service-layer logic: synchronous business rules and durable database updates.
+- Persistent CRUD: durable business state, audit logs, queryable records, and API-visible resources.
+- `cronx` scheduled tasks: periodic checks, background maintenance, delayed work, one-shot work, timeout, panic recovery, and shutdown.
+- Redis-backed persistent cron tasks: delayed work that should survive restart/deploy when Redis is available; handlers must be idempotent.
+- `messagex`: async fan-out, sequential handling, retry, DLQ, and cross-process events when Redis-backed.
+- SSE: browser-visible server push when the user needs live updates.
+- Cache: read acceleration, counters, local persistence, and multi-level caching when stale/loss behavior is acceptable.
+- Authentication and security middleware: login/logout, protected routes, token refresh/revocation, user context, role/attribute filtering, CORS, and debounce protection.
+- Outbound HTTP: external API calls, header/context propagation, timeouts, bad upstream response handling, XML/JSON/form payloads, and controlled image fetching.
+- Direct database access: only when `domainx/dx` cannot express the required operation and the risk is justified.
+
+## Candidate Design Guidance
+
+For the recommended design, describe:
+
+- business behavior: what the user will observe;
+- data impact: fields, tables, indexes, logs, or no schema change;
+- runtime behavior: sync, delayed, scheduled, event-driven, stream, cache;
+- security behavior: who can call it, how identity is proven, what data is forbidden, and which secrets/config values are required;
+- outbound behavior: external endpoint, timeout, retry/idempotency, and fallback/error behavior;
+- failure behavior: restart, duplicate execution, missing dependency, timeout, panic, retry;
+- verification: ordinary tests, integration tests, smoke checks, and skipped checks if infrastructure is missing.
+
+When alternatives matter, describe only the meaningful difference. Do not list options just to satisfy a template.
+
+## Assumption Discipline
+
+Do not silently relax a business requirement to make the implementation simpler.
+
+If the recommended design changes any of these properties, state the assumption and ask for confirmation:
+
+- timing precision: exact delay vs. scan/polling drift;
+- durability: survives restart/deploy vs. best-effort in-process work;
+- consistency: immediate update vs. eventual consistency;
+- visibility: real-time push vs. refresh/polling;
+- delivery: at-most-once, at-least-once, retry, or possible duplicate execution;
+- data ownership: existing business table vs. new field/log table/cache/message payload.
+
+Examples:
+
+- If using periodic scanning for a requirement phrased as "after N minutes", state the maximum expected delay, such as "N minutes plus up to one scan interval", and ask whether that is acceptable.
+- If using Redis-backed delayed work, state that Redis is an infrastructure prerequisite and that handlers must be idempotent.
+- If skipping SSE for a "future real-time" statement, state that the current feature will be visible through stored data/API only.
+- If using cache, state what can be stale and for how long.
+- If using memory token, state that sessions are local to the process and not suitable as a cross-instance login store.
+- If using Redis token, state the target Gorig version and Redis test requirement before claiming it works.
+- If calling a third-party service, state timeout, bad-response behavior, and which headers/secrets are sent.
+
+When a requirement uses strong language such as "must not be lost", "exactly", "immediately", "real-time", or "cannot duplicate", treat it as a blocking confirmation point unless the existing project already proves the behavior.
+
+Avoid these mistakes:
+
+- Do not choose a component only because the user used a word that resembles it.
+- Do not replace a stated timing or durability requirement with an unrelated simpler mechanism without explaining the behavior difference.
+- Do not expand into full CRUD, public APIs, or SSE just because they might be useful later.
+- Do not claim runtime behavior is verified when Redis, MySQL, MongoDB, or other required infrastructure was unavailable.
+- Do not forward user tokens to external services unless that is the explicit contract.
+- Do not put real secrets, production URLs, raw tokens, or passwords in generated examples or fixtures.
+- Do not hard-code one domain's nouns into the plan for another domain.
+
+## Confirmation Plan Shape
+
+Use this structure. Fill it with facts from the target project after inspection.
+
+```text
+Business goal:
+- <business outcome in user language>
+
+What I found in the project:
+- Related modules/models/fields:
+- Existing configuration and external dependencies:
+- Current gaps:
+
+Scenario breakdown:
+- Trigger:
+- Delay/order/periodicity:
+- Durability requirement:
+- User visibility:
+- Consistency and idempotency requirement:
+- Identity and permission requirement:
+- External service dependency:
+
+Recommended design:
+- <recommended option and why it best matches the stated business outcome>
+
+Optional tradeoffs:
+- <only include when there is a real tradeoff; omit this section when the recommendation is obvious>
+
+Current scope:
+- Must implement:
+- Out of scope but keep extension points:
+
+Need confirmation:
+- <only blocking questions>
+- <include any assumption that relaxes timing, durability, consistency, or real-time behavior>
+
+Verification plan:
+- Business-effect tests:
+- Component/infrastructure tests:
+- If a dependency is unavailable, which checks will be skipped and cannot be claimed verified:
+```
+
+## Verification Principle
+
+Verification must prove the business effect first and the framework primitive second.
+
+Examples of business-effect assertions:
+
+- An entity that still matches the delayed condition receives the intended action.
+- An entity that no longer matches the condition is not changed.
+- Duplicate or retried executions are idempotent.
+- Audit/log records are created exactly as required.
+- Real-time delivery is proven only if it is in current scope.
+
+Component-level checks support the above:
+
+- scheduled/delayed task executes, times out, recovers, or is skipped with an infrastructure reason;
+- persistent delayed task handles bad payloads and runs with Redis when available;
+- message subscriber receives payload, preserves order when required, retries, and cleans up;
+- SSE response has the correct event shape and disconnect cleanup;
+- cache hit/miss/expiry/invalidation behavior is proven.
+
+Never mark a feature verified only because the framework primitive compiled.

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

@@ -0,0 +1,301 @@
+# Cache
+
+Use this reference when a task needs cached reads, local persistence, Redis-backed cache, counters, multi-level cache, cache invalidation, or SQLite paged cache.
+
+Always inspect the target project's resolved Gorig source first. The examples below reflect the locally inspected Gorig `master` commit `35bbefb`.
+
+## Backends
+
+The inspected cache package exposes one generic interface:
+
+```go
+type Cache[T any] interface {
+    Get(key string) (T, error)
+    Set(key string, value T, expiration time.Duration) error
+    Del(key string) error
+    Exists(key string) (bool, error)
+    RPush(key string, value T) error
+    BRPop(timeout time.Duration, key string) (T, error)
+    Incr(key string) (int64, error)
+    Expire(key string, expiration time.Duration) error
+    Flush() error
+}
+```
+
+Create typed caches with `cache.New[T]`:
+
+```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)
+```
+
+Backend notes:
+
+- Memory is process-local and disappears on restart.
+- JSON persists under `.cache/<name>.json` and is useful for small local data.
+- SQLite persists under `.cache/<name>.db` and is useful for local durable cache values.
+- Redis requires configured Redis infrastructure. Do not claim Redis behavior is verified from compile-only checks.
+
+Check initialization and handle errors before depending on a cache:
+
+```go
+if memory == nil || !memory.IsInitialized() {
+    return errors.Sys("memory cache is not initialized")
+}
+```
+
+## Backend Choice
+
+Choose the cache backend from the target project's runtime needs and existing conventions.
+
+Supported Gorig cache backends in the inspected baseline:
+
+| Backend | Use when | Configuration |
+|---|---|---|
+| Memory | Fast process-local acceleration; loss on restart is acceptable. | No external config. |
+| JSON | Small local durable cache values are useful during development or simple deployments. | Cache name creates `.cache/<name>.json`. |
+| SQLite | Local durable cache values need better structure than JSON. | Cache name creates `.cache/<name>.db`; paged cache creates `.cache/<name>.pg.db`. |
+| Redis | Cross-process cache, shared deployment cache, or explicit Redis requirement. | Requires `redis.addr`, `redis.password`, `redis.db`, or `GORIG_REDIS_*` overrides. |
+
+Selection rules:
+
+- When the backend is not specified, inspect existing project conventions and present reasonable backend options with tradeoffs.
+- If the project already has a cache helper, key convention, TTL convention, or versioning scheme, prefer extending that pattern.
+- If Redis is selected or already established by the project, inspect Redis configuration before implementing.
+- If local cache is selected, prefer Memory for disposable acceleration, JSON or SQLite only when restart persistence is useful.
+- Do not introduce counters, multi-level cache, Redis, or other infrastructure unless the request requires them.
+- Treat cache as an acceleration layer unless the feature explicitly accepts loss, expiry, and cross-process state behavior.
+
+## Redis Configuration
+
+Before implementing Redis-backed cache or multi-level cache, inspect `_bin/local.yaml`, `_bin/dev.yaml`, `_bin/prod.yaml`, test config under `test/_bin/`, and deployment environment variables.
+
+The inspected cache package reads these keys:
+
+```yaml
+redis:
+  addr: 127.0.0.1:6379
+  password: ""
+  db: 0
+```
+
+Environment overrides use Gorig's `GORIG` prefix and `.` -> `_` replacement:
+
+- `redis.addr` -> `GORIG_REDIS_ADDR`
+- `redis.password` -> `GORIG_REDIS_PASSWORD`
+- `redis.db` -> `GORIG_REDIS_DB`
+
+Guidance:
+
+- Do not silently add Redis as a project dependency for Memory, JSON, or SQLite cache work.
+- When Redis is required and config is missing, use either non-secret skeleton keys in environment YAML files or rely on environment variables.
+- Never commit real Redis passwords or private connection strings.
+- Prefer `redis.addr` values such as `127.0.0.1:6379` for disposable local development and environment variables for shared environments.
+- In the inspected baseline, an empty `redis.addr` logs an initialization warning and Redis cache creation returns nil after the failed ping. Treat that as unavailable infrastructure, not as verified Redis behavior.
+- For tests, add Redis config only to disposable test configuration or inject `GORIG_REDIS_ADDR`, `GORIG_REDIS_PASSWORD`, and `GORIG_REDIS_DB` for the test process.
+
+When adding a skeleton, keep secrets empty:
+
+```yaml
+redis:
+  addr: 127.0.0.1:6379
+  password: ""
+  db: 0
+```
+
+## Cache-Aside Pattern
+
+Use cache-aside when the database or external service remains the source of truth.
+
+```go
+key := fmt.Sprintf("order:%d", id)
+
+if item, err := orderCache.Get(key); err == nil {
+    return &item, nil
+}
+
+item, err := LoadOrderFromDB(ctx, id)
+if err != nil {
+    return nil, err
+}
+if err := orderCache.Set(key, *item, 5*time.Minute); err != nil {
+    logger.Error(ctx, "set order cache failed", zap.Error(err))
+}
+return item, nil
+```
+
+After writes, delete or refresh every affected key:
+
+```go
+if err := SaveOrder(ctx, req); err != nil {
+    return err
+}
+_ = orderCache.Del(fmt.Sprintf("order:%d", req.ID))
+_ = orderCache.Del(fmt.Sprintf("order:list:%s", req.TenantID))
+```
+
+Prefer deletion over stale overwrites when list keys, permission scopes, or computed projections are hard to enumerate.
+
+## Direct Service Example
+
+Use this pattern for a detail query such as `customer.Info(ctx, id)`. Keep the exact DTO/model names from the target project.
+
+```go
+var customerInfoCache = cache.New[Resp](cache.Redis)
+
+const customerInfoTTL = 5 * time.Minute
+
+func customerInfoKey(id uint64) string {
+    return fmt.Sprintf("customer:info:%d", id)
+}
+
+func Info(ctx context.Context, id uint64) (*Resp, *errors.Error) {
+    key := customerInfoKey(id)
+    if customerInfoCache != nil && customerInfoCache.IsInitialized() {
+        if cached, err := customerInfoCache.Get(key); err == nil {
+            return &cached, nil
+        }
+    }
+
+    d, err := dx.On[model.D](ctx).WithID(id).Get()
+    if err != nil {
+        return nil, err
+    }
+    resp := ToResp(d)
+
+    if customerInfoCache != nil && customerInfoCache.IsInitialized() {
+        _ = customerInfoCache.Set(key, *resp, customerInfoTTL)
+    }
+    return resp, nil
+}
+
+func invalidateCustomerInfo(id uint64) {
+    if customerInfoCache != nil && customerInfoCache.IsInitialized() {
+        _ = customerInfoCache.Del(customerInfoKey(id))
+    }
+}
+```
+
+Call `invalidateCustomerInfo(id)` after successful update or delete. If list or page queries are cached, also delete or version the affected list/page namespace after create, update, and delete.
+
+For list/page cache keys, derive keys from normalized request DTO fields, not raw JSON:
+
+```go
+func customerListKey(req *ListReq) string {
+    normalized := fmt.Sprintf("%s|%s|%s|%s", req.CustomerNo, req.Name, req.Phone, req.Status)
+    sum := sha1.Sum([]byte(normalized))
+    return fmt.Sprintf("customer:list:%x", sum)
+}
+```
+
+When caching paginated responses whose result field is `any`, prefer a typed local cache DTO and convert back to the framework response after `Get`.
+
+## Source of Truth Boundary
+
+Cache is acceptable as an acceleration layer when:
+
+- misses can be loaded from a durable source,
+- stale values are tolerable within the TTL,
+- invalidation is deterministic enough for the business workflow, and
+- the service can continue safely if the cache is empty.
+
+Cache is not an acceptable source of truth for:
+
+- money, inventory, permissions, audit events, or legal records,
+- uniqueness checks that require durable consistency,
+- workflows where lost local files after restart would corrupt state,
+- cross-process state unless Redis or another shared backend is explicitly configured and tested.
+
+## Expiration and Invalidation
+
+```go
+err := c.Set("session:123", value, 30*time.Minute)
+ok, err := c.Exists("session:123")
+err = c.Expire("session:123", 5*time.Minute)
+err = c.Del("session:123")
+err = c.Flush()
+```
+
+Use `0` expiration only when the backend and business semantics allow no expiry. Avoid `Flush` in request paths unless the cache namespace is disposable.
+
+## Counters
+
+```go
+counter := cache.New[int64](cache.Memory, time.Minute, time.Minute)
+next, err := counter.Incr("job:attempts")
+```
+
+`Incr` is useful for local counters and Redis counters. It is not a substitute for durable database counters when exact cross-process consistency is required.
+
+## Multi-Level Cache and Singleflight
+
+`NewCacheTool` searches cache layers in order. On lower-layer hit it backfills earlier layers. On full miss it calls the loader through `singleflight`, then stores the loaded value in every layer.
+
+```go
+l1 := cache.New[Order](cache.Memory, time.Minute, time.Minute)
+l2 := cache.New[Order](cache.Redis)
+
+tool := cache.NewCacheTool[Order](ctx, []cache.Cache[Order]{l1, l2}, func(key string) (Order, error) {
+    return LoadOrderByCacheKey(ctx, key)
+})
+
+value, err := tool.Get("order:123", 5*time.Minute)
+err = tool.Set("order:123", value, 5*time.Minute)
+err = tool.Delete("order:123")
+```
+
+Use this pattern for hot reads with expensive loaders. Verify concurrent misses call the loader once for the same key in the target value type and backend combination.
+
+## SQLite Paged Cache
+
+Use SQLite paged cache for local time-series or queryable snapshots, not as a replacement for the application database.
+
+```go
+type Stat struct {
+    At     int64  `json:"at" idx:"at"`
+    Method string `json:"method" idx_group:"method_uri"`
+    URI    string `json:"uri" idx_group:"method_uri"`
+    Count  int64  `json:"count"`
+}
+
+pg, err := cache.NewSQLiteCachePage[Stat]("stat_cache")
+```
+
+The inspected implementation creates `.cache/<name>.pg.db` and auto-indexes fields from `idx` and `idx_group` tags. Verify query methods against the resolved source before using paged cache in feature code.
+
+## Key Design
+
+Use stable, namespaced keys:
+
+```text
+<app>:<env>:<module>:<entity>:<id>
+<app>:<env>:<module>:list:<tenant>:<filter-hash>
+```
+
+Rules:
+
+- Include tenant or permission scope when data visibility differs by user.
+- Hash long filter payloads instead of embedding raw JSON.
+- Do not include secrets in keys.
+- Keep list keys and item keys separate so invalidation is explicit.
+- Document all keys created by a service in the module README when cache behavior is part of the feature.
+
+## Verification Checklist
+
+Local backends:
+
+- Memory: set, get, miss, expiry, delete, counter, flush.
+- JSON: persistence file creation, get after recreate, delete, expiry.
+- SQLite: persistence file creation, get after recreate, delete, expiry.
+- Multi-level cache: L1 miss, L2 hit backfill, full miss loader, delete across layers.
+- Singleflight: concurrent same-key misses call the loader once.
+
+Redis:
+
+- Run only with disposable or explicitly supplied Redis configuration.
+- Verify set/get, expiry, delete, counter, and cross-process visibility.
+- Report Redis as skipped when configuration is absent.
+
+Delivery evidence must include exact commands, backend configuration, skipped checks, and whether cache is used as acceleration or as state.