Deployed 4a964a9 with MkDocs version: 1.6.1

errors/index.html

@@ -1087,7 +1087,7 @@ <h2 id="see-also">See also<a class="headerlink" href="#see-also" title="Permanen
 <ul>
 <li><strong><a href="../resilience/">Resilience reference</a></strong> — <code>AsyncRetry</code>, <code>RetryBudget</code>, <code>AsyncBulkhead</code> parameter tables.</li>
 <li><strong><a href="../middleware/">Middleware guide</a></strong> — the <code>@async_on_error</code> decorator can translate exceptions into responses.</li>
-<li><strong><code>planning/engineering.md</code> §4</strong> — the formal exception contract.</li>
+<li><strong><code>architecture/errors.md</code></strong> — the formal exception contract.</li>
 </ul>
 
 

index.html

@@ -1081,7 +1081,7 @@ <h2 id="where-to-go-next">Where to go next<a class="headerlink" href="#where-to-
 <li><strong><a href="errors/">Errors reference</a></strong> — the full exception tree, catching strategies, <code>exc.response.*</code> access pattern.</li>
 <li><strong><a href="testing/">Testing guide</a></strong> — mock-transport injection pattern for testing code that uses <code>httpware</code>.</li>
 <li><strong><a href="recipes/modern-di/">Recipes</a></strong> — wiring <code>AsyncClient</code> into a <code>modern-di</code> container.</li>
-<li><strong><a href="https://github.com/modern-python/httpware/blob/main/planning/engineering.md">Engineering Notes</a></strong> — design invariants, the three protocol seams, exception contract, module layout, testing patterns, optional-extras pattern. Lives in the repo at <code>planning/engineering.md</code>.</li>
+<li><strong><a href="https://github.com/modern-python/httpware/blob/main/architecture/overview.md">Architecture Notes</a></strong> — per-capability design notes — invariants, the three protocol seams, exception contract, module layout, testing patterns — under <code>architecture/</code>. Lives in the repo under <code>architecture/</code>.</li>
 <li><strong><a href="dev/contributing/">Contributing</a></strong> — setup, conventions, workflow.</li>
 <li><strong><a href="https://github.com/modern-python/httpware/releases">Release notes</a></strong> — per-version changelogs.</li>
 </ul>

middleware/index.html

@@ -978,7 +978,7 @@ <h2 id="when-not-to-write-a-middleware">When NOT to write a middleware<a class="
 <li><strong>Redaction:</strong> Use a <code>logging.Filter</code> on the consumer side. <code>httpware</code> deliberately does no redaction in-library (per the 0.6.0 observability design).</li>
 <li><strong>URL or header validation:</strong> <code>httpx2</code> owns it. Don't reimplement.</li>
 <li><strong>Per-call behavior that doesn't apply to other calls:</strong> Pass through <code>request.extensions=</code> (or the <code>extensions=</code> kwarg at the call site) instead. Middleware exists for <em>cross-cutting</em> concerns.</li>
-<li><strong>HTTP-level span creation for tracing:</strong> Install <code>opentelemetry-instrumentation-httpx</code> instead of writing an OTel middleware in httpware. We retired story <code>5-4</code> (standalone OTel middleware) for this reason — <code>opentelemetry-instrumentation-httpx</code> already covers transport-level tracing, and a separate httpware layer would duplicate it. See <code>planning/engineering.md</code> §8.</li>
+<li><strong>HTTP-level span creation for tracing:</strong> Install <code>opentelemetry-instrumentation-httpx</code> instead of writing an OTel middleware in httpware. We retired story <code>5-4</code> (standalone OTel middleware) for this reason — <code>opentelemetry-instrumentation-httpx</code> already covers transport-level tracing, and a separate httpware layer would duplicate it. See <code>architecture/middleware.md</code>.</li>
 </ul>
 <h2 id="wiring-opentelemetry">Wiring OpenTelemetry<a class="headerlink" href="#wiring-opentelemetry" title="Permanent link">&para;</a></h2>
 <p><code>httpware[otel]</code> only ships <code>opentelemetry-api</code>. To make the observability events emitted by <code>AsyncRetry</code> and <code>AsyncBulkhead</code> visible, you also need:</p>
@@ -1049,7 +1049,7 @@ <h2 id="sync-middleware">Sync middleware<a class="headerlink" href="#sync-middle
 <p>Sync and async middleware classes do not interop: a <code>Middleware</code> cannot be passed to <code>AsyncClient(middleware=...)</code> and vice versa. Pick the flavor matching your client.</p>
 <h2 id="see-also">See also<a class="headerlink" href="#see-also" title="Permanent link">&para;</a></h2>
 <ul>
-<li><strong><code>planning/engineering.md</code> §3 (Seam A)</strong> — the formal protocol contract and why the chain is frozen at construction.</li>
+<li><strong><code>architecture/middleware.md</code> (Seam A)</strong> — the formal protocol contract and why the chain is frozen at construction.</li>
 <li><strong><code>src/httpware/middleware/resilience/</code></strong> — <code>AsyncRetry</code>, <code>AsyncBulkhead</code>, <code>RetryBudget</code> as real-world consumers of this exact protocol.</li>
 <li><strong><a href="../#with-resilience-middleware">Quick-Start composition example</a></strong> — composing built-in middleware.</li>
 </ul>

resilience/index.html

@@ -1853,7 +1853,7 @@ <h2 id="see-also">See also<a class="headerlink" href="#see-also" title="Permanen
 <li><strong><a href="../middleware/">Middleware guide</a></strong> — write your own resilience middleware against the same protocol <code>AsyncRetry</code> and <code>AsyncBulkhead</code> use.</li>
 <li><strong><a href="../errors/">Errors reference</a></strong> — <code>RetryBudgetExhaustedError</code>, <code>BulkheadFullError</code>, <code>CircuitOpenError</code>, and the broader exception tree.</li>
 <li><strong><a href="../#observability">Observability</a></strong> — the operational events these middleware emit.</li>
-<li><strong><code>planning/engineering.md</code> §3</strong> — the formal Middleware/Seam-A contract.</li>
+<li><strong><code>architecture/middleware.md</code></strong> — the formal Middleware/Seam-A contract.</li>
 </ul>
 
 

search/search_index.json

@@ -948,7 +948,7 @@ <h2 id="see-also">See also<a class="headerlink" href="#see-also" title="Permanen
 <ul>
 <li><strong><a href="../middleware/">Middleware guide</a></strong> — write the middleware you're testing.</li>
 <li><strong><a href="../resilience/">Resilience reference</a></strong> — testing <code>AsyncRetry</code>/<code>AsyncBulkhead</code> configurations.</li>
-<li><strong><code>planning/engineering.md</code> §6</strong> — the project's own testing patterns (Hypothesis property-based tests, <code>pytest-asyncio</code> auto-mode, the <code>RecordedTransport</code>-was-removed history).</li>
+<li><strong><code>architecture/testing.md</code></strong> — the project's own testing patterns (Hypothesis property-based tests, <code>pytest-asyncio</code> auto-mode, the <code>RecordedTransport</code>-was-removed history).</li>
 </ul>