docs: pre-release docs pass for 0.3.8

[allen0099]

Closes #214

Summary

Each change is documented. Checked every ## [Unreleased] entry and every entry collected in #286 against the guides and the code.

• HTTP_CACHING: invalidate() no longer claims it never raises. It returns False without a backend, but backend errors propagate.
• HTTP_CACHING: new paragraph saying a custom key builder only runs when @cache uses the backend (@cache wrapper: build the key lazily and tidy the request check #182).
• LOCK: the opening now describes a lease, not a fencing lock (see CacheLock: optional automatic renewal and a way to detect a lost lock #250).
• LOCK: new Backend bullet. There is no MemoryBackend fallback, so acquire() raises BackendNotFoundError when no backend is set.
• LOCK: the Redis note now names both SET NX EX and the Lua scripts.
• Already correct on master, left unchanged:
  • require_user_session / AuthenticatedSession, including UserSessionDep in the dependency list;
  • the JWT short-key warning;
  • get_session(touch=True);
  • cache-key escaping;
  • media_type in /cached-records;
  • the CacheBackend fallback;
  • rotate_session_id and clear().

Wrong statements from the review comment

• BACKENDS, HTTP_CACHING (EN and zh-TW) and CLAUDE.md: only the Redis and Memcached backends prefix their keys; MemoryBackend has no prefix.
• BACKENDS: counter_entry(n) is qualified for Memcached, whose counters are unsigned. A negative n there cannot be incremented and raises CacheXError (Memcached: validate key_prefix, and qualify the counter_entry(n) claim #239). Checked against a live Memcached 1.6 server: counter_entry(5) increments to 7, while counter_entry(-3) raises CacheXError.
• APP_CACHE (EN and zh-TW): CacheManager prefixes that nest (cache: and cache:users:) share clear(), and an empty prefix clears everything (CacheManager: typed reads, incr, and get_many/set_many #249).

zh-TW parity

• New LOCK.md and CONTRIBUTING.md translations, added to the zh-TW nav.
  • The 開發 group now links the local 貢獻指南.
  • 開發指南 still points to the English site.
• index.md now matches the README:
  • adds a 分散式鎖 link;
  • 貢獻指南 is local;
  • headings carry {#id}s matching the English page (they had none).
• BACKENDS: added the four missing passages:
  • the Redis clear_pattern() logical-key/deprecation bullet;
  • the encoding="utf-8" paragraph and its inline comment;
  • the full increment sentence;
  • the expire_if_equals bullet (「這五個方法」).
• HTTP_CACHING, CACHE_FLOW: the TTL-less (ttl=None / ttl=0) behaviour was stale. The note, table row, pseudo-code and max-age cell now say the backend is neither read nor written.
• docs/DEVELOPMENT.md ("Traditional Chinese translation") records that api/*, DEVELOPMENT.md and the changelog stay English-only.

Examples match the API

• JWT_CLAIMS (EN and zh-TW): the custom-serializer examples are rewritten on a standalone CustomClaimsJWTSerializer.
  • It implements the TokenSerializer protocol with PyJWT and reads the public SessionConfig fields.
  • It no longer reads JWTTokenSerializer private attributes.
  • Subclasses add claims through extra_claims(), required_claims and check_claims().
  • The key-rotation sketch, the claim-validation snippet and the test example are updated to match.
  • No new public API.
• JWT_CLAIMS: examples use FastAPICacheXSessionMiddleware instead of the deprecated SessionMiddleware. The complete example guards the profile route with require_user_session.
• No docs use the memcache extra except where they describe its deprecation.

CLAUDE.md

• Added a CacheLock subsystem entry and expire_if_equals ("five" atomic primitives).
• Corrected the key-prefix statement.
• Updated the session middleware and token transports.

Verification

• Both strict builds pass with no issues:
  • uv run --group docs zensical build --strict --clean
  • uv run --group docs zensical build --strict --clean -f zensical.zh-TW.toml
• Heading ids of every translated page match the English page, compared in the built HTML. This covers index, LOCK and CONTRIBUTING.
• EN/zh-TW structure (headings, lists, tables, code blocks) and inline code spans were compared per page. This check found the stale CACHE_FLOW passages.
• Every from fastapi_cachex… import … in the Python code blocks of both languages resolves against this branch (44 names).
• Scratch scripts (not committed) exercised the examples on a MemoryBackend:

  • JWT. The serializer base class, both examples, both test functions and the complete app ran through TestClient:

    • custom claims, iss/aud, and exp following expires_at including a sliding renewal;
    • rejection of a missing jti, the wrong audience, a tampered signature, another tenant and another API version, all as SessionTokenError;
    • 401 without a token and for another tenant's token.

    It ran with warnings as errors; there were none.

  • LOCK.

    • Both examples; acquire() without a backend raising BackendNotFoundError; LockTimeoutError from async with.
    • RuntimeError on re-acquiring the same instance.
    • After expiry, extend()/release() return False and another holder gets the lock.
    • A finite timeout returns False; the default blocking acquire() waits until the lock is released.
• pre-commit on the changed files and uv lock --check pass.

CHANGELOG

None: docs only.