docs: seção Cache na página de documentação (docs.html)

static/docs.html

@@ -56,6 +56,7 @@
           <a href="#autenticacao" class="nav-link block px-3 py-1.5 rounded-lg text-muted hover:text-ink hover:bg-paper-2 transition">Autenticação</a>
           <a href="#convencoes" class="nav-link block px-3 py-1.5 rounded-lg text-muted hover:text-ink hover:bg-paper-2 transition">Convenções</a>
           <a href="#resposta" class="nav-link block px-3 py-1.5 rounded-lg text-muted hover:text-ink hover:bg-paper-2 transition">Anatomia da resposta</a>
+          <a href="#cache" class="nav-link block px-3 py-1.5 rounded-lg text-muted hover:text-ink hover:bg-paper-2 transition">Cache</a>
           <div class="pt-3 pb-1 px-3 text-xs uppercase tracking-wider text-muted/60">Endpoints</div>
           <a href="#consultas" class="nav-link block px-3 py-1.5 rounded-lg text-muted hover:text-ink hover:bg-paper-2 transition">Consultas</a>
           <a href="#processo" class="nav-link block px-3 py-1.5 rounded-lg text-muted hover:text-ink hover:bg-paper-2 transition">Andamentos & processo</a>
@@ -212,6 +213,27 @@ <h2 class="font-display text-3xl font-semibold tracking-tight">Anatomia da respo
           </div>
         </section>
 
+        <!-- cache -->
+        <section id="cache" class="scroll-mt-24">
+          <h2 class="font-display text-3xl font-semibold tracking-tight">Cache</h2>
+          <p class="text-muted leading-relaxed mt-3 max-w-2xl">As respostas <strong>JSON</strong> de <code class="font-mono text-sm text-pine-deep">/v1/*</code> são cacheadas em memória (read-only), com <em>single-flight</em> e <em>serve-stale</em> quando o SEI cai. Cada resposta traz headers para o cliente decidir.</p>
+          <div class="grid md:grid-cols-3 gap-4 mt-6">
+            <div class="rounded-2xl border border-ink/8 bg-white/50 p-5">
+              <div class="font-display text-pine text-lg font-semibold">X-Cache</div>
+              <p class="text-muted text-sm mt-2 leading-relaxed"><code class="font-mono text-pine-deep">HIT</code> · <code class="font-mono text-pine-deep">MISS</code> · <code class="font-mono text-pine-deep">STALE</code> · <code class="font-mono text-pine-deep">PARTIAL</code>. <code class="font-mono text-pine-deep">STALE</code> = SEI fora do ar, servindo o último valor bom.</p>
+            </div>
+            <div class="rounded-2xl border border-ink/8 bg-white/50 p-5">
+              <div class="font-display text-pine text-lg font-semibold">Cache-Control · Age</div>
+              <p class="text-muted text-sm mt-2 leading-relaxed"><code class="font-mono text-pine-deep">private, max-age=&lt;ttl&gt;</code> + <code class="font-mono text-pine-deep">Age</code> coerentes com o TTL (listas ~6h; processo ~30s).</p>
+            </div>
+            <div class="rounded-2xl border border-ink/8 bg-white/50 p-5">
+              <div class="font-display text-pine text-lg font-semibold">Forçar fresco</div>
+              <p class="text-muted text-sm mt-2 leading-relaxed">Envie <code class="font-mono text-pine-deep">Cache-Control: no-cache</code> (revalida) ou <code class="font-mono text-pine-deep">no-store</code> (busca fresco sem persistir).</p>
+            </div>
+          </div>
+          <p class="text-muted text-sm leading-relaxed mt-4 max-w-2xl">Faults de SOAP de "não encontrado" são lembrados por pouco tempo (negative caching). O endpoint SSE <code class="font-mono text-sm text-pine-deep">/v1/andamentos/stream</code> é exceção: não carrega esses headers (é um fluxo de eventos), mas respeita <code class="font-mono text-pine-deep">no-cache</code>/<code class="font-mono text-pine-deep">no-store</code>. Estatísticas em <code class="font-mono text-sm text-pine-deep">/health</code>.</p>
+        </section>
+
         <!-- CONSULTAS -->
         <section id="consultas" class="scroll-mt-24">
           <div class="flex items-center gap-3">