docs: re-collect wiki sites (doc-forge, openapi-first)

Reflect rebuilt consumer wikis in the hub: doc-forge gains the MkDocs cross-kind link notes; openapi-first gains the codegen --template-style content. Purely cosmetic (toolchain escaping) and sitemap mtime deltas were left out.

doc-forge/wiki/05_development/05_mkdocs_configs/index.html

@@ -675,6 +675,15 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#cross-kind-links" class="md-nav__link">
+    <span class="md-ellipsis">
+      🔗 Cross-kind links
+    </span>
+  </a>
+  
 </li>
       
         <li class="md-nav__item">
@@ -782,6 +791,17 @@ built-in templates entirely.</p>
 </ul>
 <p>Commit <code>docs/mkdocs.{kind}.yml</code> so served docs are reproducible from source.</p>
 <hr />
+<h2 id="cross-kind-links">🔗 Cross-kind links</h2>
+<p>Kinds are separate MkDocs sites served side by side under <code>/&lt;repo&gt;/&lt;kind&gt;/</code>,
+so a wiki page may link to the library reference with a source-relative path
+such as <code>../lib/13_library_registry/</code>. MkDocs only rewrites links that point
+inside <code>docs_dir</code>; anything reaching a sibling kind is emitted verbatim and,
+under <code>use_directory_urls</code>, resolves into <code>&lt;kind&gt;/&lt;kind&gt;/</code> and breaks.</p>
+<p>The <code>docforge-linkfix</code> plugin (part of doc-forge, enabled in the wiki
+template) fixes this at render time: it rewrites <code>../lib/</code>, <code>../api/</code>, and
+<code>../wiki/</code> links to climb to the repository root, so they resolve correctly
+however deeply the page is nested.</p>
+<hr />
 <h2 id="related">Related</h2>
 <ul>
 <li><a href="../04_mcp_guide/">04 – MCP Guide</a></li>

openapi-first/wiki/03_use_cases/04_codegen/index.html

@@ -671,6 +671,15 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#handler-shapes" class="md-nav__link">
+    <span class="md-ellipsis">
+      Handler shapes
+    </span>
+  </a>
+  
 </li>
         
       </ul>
@@ -894,6 +903,10 @@
 <td><code>--package</code></td>
 <td>Emit <code>&lt;resource&gt;/routes.py</code> packages (with <code>__init__.py</code>) instead of flat <code>&lt;resource&gt;.py</code></td>
 </tr>
+<tr>
+<td><code>--template-style</code></td>
+<td>Emit <code>async def</code> handlers with a JSON body parameter named <code>body</code> (the standards-template convention) plus a service-resolution hint, instead of sync <code>def</code> handlers taking <code>payload</code></td>
+</tr>
 </tbody>
 </table>
 <p>Why bother? Because <code>bind_routes</code> (in <a href="../../02_components/">02 – Components</a>) needs an <code>operationId</code> → handler <strong>exactly</strong> matching the spec. Codegen guarantees you never type a handler name wrong — it wears the same <code>operationId</code> the spec declares.</p>
@@ -903,6 +916,13 @@
 <li><code>multipart/form-data</code> and <code>application/x-www-form-urlencoded</code> bodies expand to one parameter per schema property: <code>UploadFile = File(...)</code> for <code>format: binary</code>, <code>Form(...)</code> otherwise — not an opaque <code>payload: dict</code>. Fields are required only when listed in the schema's <code>required</code>.</li>
 </ul>
 <p>The stubs <code>raise NotImplementedError</code>; fill each body in (typically by resolving a service from <code>request.app.state</code>).</p>
+<h3 id="handler-shapes">Handler shapes</h3>
+<p>Both shapes bind equally — the router resolves the handler by <code>operationId</code> and introspects the FastAPI signature, so it never inspects the request body:</p>
+<ul>
+<li><strong>Default (sync stub):</strong> <code>def create_item(payload: ItemInput, response: Response):</code> — the body parameter is <code>payload</code>.</li>
+<li><strong><code>--template-style</code>:</strong> <code>async def create_item(request: Request, body: ItemInput, response: Response):</code> — matches the standards template (<code>async def</code>, <code>body</code> parameter, a <code>request.app.state.db_resources["&lt;resource&gt;_svc"]</code> hint).</li>
+</ul>
+<p>Use <code>--template-style</code> when generating against the standards template so the scaffold matches the hand-written handlers you will keep.</p>
 <blockquote>
 <p><strong>Note:</strong> <code>models</code> / <code>routes</code> are build-time tooling. They do <strong>not</strong> run at runtime, and templates (the Bake-your-stuff section of <a href="../02_templates/">02 – Templates</a>) scaffold a working server out-of-the-box for greenfield projects.</p>
 </blockquote>

standards/src/hooks.py

@@ -0,0 +1,36 @@
+"""MkDocs hook: rebase cross-kind links to the repository root.
+
+The standards wiki links to the sibling library reference with
+source-relative paths such as ``../lib/13_library_registry/``. MkDocs only
+rewrites links whose target lives inside ``docs_dir``, so those links are
+emitted verbatim and, under ``use_directory_urls``, resolve into
+``/standards/wiki/lib/...`` and break.
+
+This hook rewrites ``../lib/``, ``../api/`` and ``../wiki/`` links to climb to
+the repository root, so they resolve to ``/<repo>/<kind>/`` regardless of how
+deeply the page is nested. It mirrors the ``docforge-linkfix`` MkDocs plugin.
+"""
+
+from __future__ import annotations
+
+import re
+
+_CROSS_KIND_LINK = re.compile(r"\]\((?:\.\./)+(lib|api|wiki)/")
+
+
+def on_page_markdown(markdown, *, page, config, files):
+    """Prefix cross-kind links with the depth required to reach the repo root.
+
+    Args:
+        markdown (str): The raw Markdown source of the current page.
+        page: The page being rendered; its destination URI determines how many
+            directory levels the output sits below the site root.
+        config: The active MkDocs configuration (unused).
+        files: The collection of files in the site (unused).
+
+    Returns:
+        str: The Markdown with cross-kind links rebased to the repo root.
+    """
+    depth = page.file.dest_uri.count("/")
+    prefix = "../" * (depth + 1)
+    return _CROSS_KIND_LINK.sub(lambda match: f"]({prefix}{match.group(1)}/", markdown)

standards/src/mkdocs.wiki.yml

@@ -4,6 +4,9 @@ docs_dir: wiki
 site_dir: ../wiki
 use_directory_urls: true
 
+hooks:
+  - hooks.py
+
 theme:
   name: material
   palette:

standards/wiki/01_overview/index.html

@@ -671,7 +671,7 @@ port/adapter binding, performed by the composition root at startup.</p>
 <li><strong>Spec-first.</strong> The HTTP contract is declared in <code>openapi.yaml</code>; route
    handlers are looked up by <code>operationId</code>. There are no decorator routers.</li>
 <li><strong>Reuse the libraries.</strong> Orchestration, DI, Mongo repositories, ingestion,
-   auth, and docs come from internal libraries — see the <a href="../lib/13_library_registry/">Library
+   auth, and docs come from internal libraries — see the <a href="../../lib/13_library_registry/">Library
    Registry</a>.</li>
 <li><strong>Explicit state machines.</strong> Long-running work moves through explicit,
    durable statuses and can pause for human input.</li>

standards/wiki/03_start_an_app/index.html

@@ -579,7 +579,7 @@ copying Tier B template components.</p>
 <blockquote>
 <p><strong>Doc model:</strong> this page is the human entry point. The deterministic,
 machine-facing checklist lives in the reference page
-<a href="../lib/01_build_recipe/">Build Recipe</a>, served as <code>docs://modules/build_recipe</code>.</p>
+<a href="../../lib/01_build_recipe/">Build Recipe</a>, served as <code>docs://modules/build_recipe</code>.</p>
 </blockquote>
 <hr />
 <h2 id="what-the-agent-needs-from-you">🧾 What the agent needs from you</h2>
@@ -592,7 +592,7 @@ machine-facing checklist lives in the reference page
    the families and their input formats (or "none").</li>
 <li><strong>Auth needed now?</strong> Default <strong>no</strong>. Auth is deferred (<code>py-jwt</code> primitives
    only), and an authless app is just a spec with no <code>security</code> keys — see
-   <a href="../lib/04_spec_first_routing/#authless-apps">Spec-First Routing → Authless apps</a>.</li>
+   <a href="../../lib/04_spec_first_routing/#authless-apps">Spec-First Routing → Authless apps</a>.</li>
 <li><strong>Integrations.</strong> Mongo, ingestion formats, email, LLM provider.</li>
 </ol>
 <p>If you can state axes 1 and 2, the rest is mechanical.</p>
@@ -619,9 +619,9 @@ machine-facing checklist lives in the reference page
 <hr />
 <h2 id="reference">📚 Reference</h2>
 <ul>
-<li><a href="../lib/01_build_recipe/">Build Recipe</a> — the deterministic checklist</li>
-<li><a href="../lib/12_genericity_matrix/">Genericity Matrix</a> — Tier A / B / C</li>
-<li><a href="../lib/13_library_registry/">Library Registry</a> — the Tier A catalog</li>
+<li><a href="../../lib/01_build_recipe/">Build Recipe</a> — the deterministic checklist</li>
+<li><a href="../../lib/12_genericity_matrix/">Genericity Matrix</a> — Tier A / B / C</li>
+<li><a href="../../lib/13_library_registry/">Library Registry</a> — the Tier A catalog</li>
 <li><a href="../02_components/">App Components</a> — the component model</li>
 </ul>
 <hr />

standards/wiki/04_development/02_releasing/index.html

@@ -622,10 +622,10 @@
 
 <h1 id="releasing-versioning">Releasing &amp; Versioning</h1>
 <p>How to cut a release of any Aetos repository. The rule lives in the reference
-page <a href="../lib/11_versioning_and_changelog/">Versioning &amp; Changelog</a>; this is the
+page <a href="../../../lib/11_versioning_and_changelog/">Versioning &amp; Changelog</a>; this is the
 runbook you follow.</p>
 <p>Every repository is one of two Drone shapes — a <strong>PyPI package</strong> or a <strong>Docker
-deployment</strong> (<a href="../lib/10_drone_pipelines/">Drone Pipelines</a>). Both release the
+deployment</strong> (<a href="../../../lib/10_drone_pipelines/">Drone Pipelines</a>). Both release the
 same way: the version bump and changelog promotion go <strong>in the merge request</strong>,
 and the tag is created on the merged commit.</p>
 <hr />
@@ -750,7 +750,7 @@ outage):</p>
 <hr />
 <h2 id="related">Related</h2>
 <ul>
-<li><a href="../01_testing/">Testing &amp; Quality Gates</a> · <a href="../lib/11_versioning_and_changelog/">Versioning &amp; Changelog</a> · <a href="../lib/10_drone_pipelines/">Drone Pipelines</a></li>
+<li><a href="../01_testing/">Testing &amp; Quality Gates</a> · <a href="../../../lib/11_versioning_and_changelog/">Versioning &amp; Changelog</a> · <a href="../../../lib/10_drone_pipelines/">Drone Pipelines</a></li>
 </ul>