docs: gardening Apr 2026 (#40)

* docs: gardening Apr 2026 — update stale architecture, quality, golden-principles

* docs: fix module tree and golden-principles consistency

- Add X402.Utils and X402.Header to module structure tree
- Add (added v0.3.2) annotation to Principle 12
- Fix Principle 1 wording: 'Any facilitator URL' → 'Any HTTPS facilitator URL'
  to remove conflict with Principle 12

Author: cardotrejos

docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture — x402 Elixir SDK
 
-> Last updated: 2026-02-25
+> Last updated: 2026-04-01
 
 ## Overview
 
@@ -17,6 +17,8 @@ A pure Elixir library implementing the x402 HTTP payment protocol. Ships as a He
 
 ```
 X402                         # Top-level convenience API (delegates to submodules)
+├── Utils                    # Shared utilities (decimal parsing, common helpers)
+├── Header                   # Shared header utilities
 ├── PaymentRequired          # Encode/decode PAYMENT-REQUIRED header (Base64 JSON)
 ├── PaymentSignature         # Decode and validate PAYMENT-SIGNATURE header
 ├── PaymentResponse          # Encode PAYMENT-RESPONSE header
@@ -91,3 +93,14 @@ Only raise on programmer errors (wrong type passed to function, etc.).
 [:x402, :settle, :stop]
 [:x402, :settle, :exception]
 ```
+
+## Recent Changes (v0.3.2 → v0.3.3)
+
+- **`X402.Utils`** — new centralized utilities module; decimal parsing optimized, shared helpers extracted from multiple modules
+- **`X402.Facilitator.HTTP`** — TLS peer verification now enforced; secure pool options exposed via `HTTP.secure_pool_opts/0`; HTTPS-only on `base_url` (rejects `http://` at config time)
+- **`X402.PaymentSignature`** — format validation tightened; 8KB size cap enforced to prevent oversized headers
+- **`X402.PaymentRequired` / `X402.PaymentResponse`** — 8KB payload size cap added
+- **`X402.Extensions.SIWX.ETSStorage`** — ETS size cap added; read consistency fixes; atomic claim to prevent double-settle; safe cache eviction
+- **Elixir minimum** — bumped to `~> 1.19`
+- **`X402.Header`** — new shared header utilities module
+- **`X402.Wallet`** — Solana address validation tightened

docs/golden-principles.md

@@ -3,7 +3,7 @@
 > These are non-negotiable. Every PR is judged against them.
 
 ## 1. Zero Lock-In
-The library never forces a specific facilitator, chain, HTTP client, or framework. Users bring their own `Finch` process. Any facilitator URL is accepted. Any CAIP-2 network is valid.
+The library never forces a specific facilitator, chain, HTTP client, or framework. Users bring their own `Finch` process. Any HTTPS facilitator URL is accepted. Any CAIP-2 network is valid.
 
 **Violation:** Hardcoding Coinbase's facilitator URL. Requiring a specific HTTP client at compile time.
 
@@ -51,3 +51,13 @@ Unit tests use Bypass or Mox. Real HTTP calls are forbidden in test suite. CI ne
 If a PR drops coverage below 90%, it is not merged. Period. Coverage is a floor, not a vanity metric.
 
 **Violation:** Merging a PR with coverage at 88% "because it's close enough".
+
+## 11. TLS Must Be Verified (added v0.3.2)
+All HTTP connections to the facilitator must use TLS peer verification. No `:verify_none` in production configuration. `HTTP.secure_pool_opts/0` is the canonical source of pool config.
+
+**Violation:** Passing `[transport_opts: [verify: :verify_none]]` to `Finch.start_link`.
+
+## 12. Enforce HTTPS on Facilitator URL (added v0.3.2)
+The facilitator `base_url` must start with `https://`. This is validated at `Facilitator.start_link/1` time, not at call time.
+
+**Violation:** Accepting an `http://` facilitator URL at startup without raising.

docs/quality.md

@@ -1,16 +1,16 @@
 # Quality Status — x402 Elixir SDK
 
-> Last updated: 2026-02-25
+> Last updated: 2026-04-01
 
 ## Current Grades
 
 | Area | Grade | Notes |
 |------|-------|-------|
-| Tests | A- | >89% line coverage (ExCoveralls), doctests on all pure functions |
+| Tests | A | >90% line coverage (ExCoveralls), doctests on all pure functions; new HTTP + PaymentSignature tests added |
 | Architecture | A | Flat modules, behaviours, minimal deps — Dashbit-level |
 | Docs | A | hexdocs published, @moduledoc + @doc + @spec on all publics |
 | Type Safety | A | Dialyzer-clean, full typespecs |
-| Security | B+ | No secrets stored, wallet validation tested, SIWX needs more fuzz |
+| Security | A- | TLS peer verification enforced, HTTPS-only base_url, 8KB size caps on all headers, atomic ETS claim |
 | Optional Deps | A | Compiles cleanly with `--no-optional-deps` |
 
 ## Coverage Target