chore: collect auth-server wiki and lib refresh

Picks up the rewritten auth-server wiki (platform anatomy theme) and the regenerated lib artifacts, including the new pep-typed marker bounce.
2026-09-16 19:51:24 +05:30
parent 7aadae1736
commit a115df113d
12 changed files with 233 additions and 154 deletions
--- a/auth-server/wiki/01_centralized_auth/index.html
+++ b/auth-server/wiki/01_centralized_auth/index.html
@@ -412,7 +412,7 @@
        <li class="md-nav__item">
  <a href="#the-identity-model" class="md-nav__link">
    <span class="md-ellipsis">
-      The identity model
+      🧬 The identity model
    </span>
  </a>
  
@@ -421,7 +421,7 @@
        <li class="md-nav__item">
  <a href="#token-contract" class="md-nav__link">
    <span class="md-ellipsis">
-      Token contract
+      🎟️ Token contract
    </span>
  </a>
  
@@ -430,7 +430,7 @@
        <li class="md-nav__item">
  <a href="#how-the-ecosystem-trusts-the-server" class="md-nav__link">
    <span class="md-ellipsis">
-      How the ecosystem trusts the server
+      🤝 How the ecosystem trusts the server
    </span>
  </a>
  
@@ -439,7 +439,16 @@
        <li class="md-nav__item">
  <a href="#benefits" class="md-nav__link">
    <span class="md-ellipsis">
-      Benefits
+      💡 Benefits
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#read-next" class="md-nav__link">
+    <span class="md-ellipsis">
+      📚 Read Next
    </span>
  </a>
  
@@ -557,11 +566,12 @@



-<h1 id="centralized-authentication">Centralized Authentication</h1>
+<h1 id="centralized-authentication">🔗 Centralized Authentication</h1>
 <p>The Aetoskia Auth Server acts as the <strong>single identity provider</strong> for every
 application in the Aetos Platform ecosystem. The model is deliberately small
 and uniform.</p>
-<h2 id="the-identity-model">The identity model</h2>
+<hr />
+<h2 id="the-identity-model">🧬 The identity model</h2>
 <div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1"> 1</a></span>
 <span class="normal"><a href="#__codelineno-0-2"> 2</a></span>
 <span class="normal"><a href="#__codelineno-0-3"> 3</a></span>
@@ -599,7 +609,8 @@ and uniform.</p>
  client, and further use is prevented only by expiry or revocation through
  introspection-driven policies.</li>
 </ul>
-<h2 id="token-contract">Token contract</h2>
+<hr />
+<h2 id="token-contract">🎟️ Token contract</h2>
 <p>A valid access token is an HS256 JWT with exactly two claims:</p>
 <div class="language-json highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1">1</a></span>
 <span class="normal"><a href="#__codelineno-1-2">2</a></span>
@@ -615,7 +626,8 @@ and uniform.</p>
 </ul>
 <p>There are no scopes or roles inside the token; authorization decisions belong
 to the consuming service, while identity and authenticity belong here.</p>
-<h2 id="how-the-ecosystem-trusts-the-server">How the ecosystem trusts the server</h2>
+<hr />
+<h2 id="how-the-ecosystem-trusts-the-server">🤝 How the ecosystem trusts the server</h2>
 <ol>
 <li><strong>Users authenticate once</strong> via <code>/login</code> and receive a token.</li>
 <li><strong>Services accept that token</strong> as proof of identity after verifying it
@@ -626,13 +638,19 @@ to the consuming service, while identity and authenticity belong here.</p>
 </ol>
 <p>This keeps authentication centralized while leaving each service in control
 of its own authorization rules.</p>
-<h2 id="benefits">Benefits</h2>
+<hr />
+<h2 id="benefits">💡 Benefits</h2>
 <ul>
 <li>New services onboard with a client library call, not a new auth system.</li>
 <li>Credential storage, hashing, and issuance policies evolve in one place.</li>
 <li>A single <code>JWT_SECRET</code> rotation strategy protects the whole platform.</li>
 </ul>
 <hr />
+<h2 id="read-next">📚 Read Next</h2>
+<ul>
+<li><a href="../02_how_to_use/">How to Use</a> — register, login, and call endpoints.</li>
+<li><a href="../03_platform_integration/">Platform Integration</a> — wiring the token into services.</li>
+</ul>



--- a/auth-server/wiki/02_how_to_use/index.html
+++ b/auth-server/wiki/02_how_to_use/index.html
@@ -434,7 +434,7 @@
        <li class="md-nav__item">
  <a href="#register-a-user" class="md-nav__link">
    <span class="md-ellipsis">
-      Register a user
+      👤 Register a user
    </span>
  </a>
  
@@ -443,7 +443,7 @@
        <li class="md-nav__item">
  <a href="#log-in-to-get-a-token" class="md-nav__link">
    <span class="md-ellipsis">
-      Log in to get a token
+      🔑 Log in to get a token
    </span>
  </a>
  
@@ -452,7 +452,7 @@
        <li class="md-nav__item">
  <a href="#call-a-protected-endpoint" class="md-nav__link">
    <span class="md-ellipsis">
-      Call a protected endpoint
+      🔒 Call a protected endpoint
    </span>
  </a>
  
@@ -461,7 +461,7 @@
        <li class="md-nav__item">
  <a href="#log-out" class="md-nav__link">
    <span class="md-ellipsis">
-      Log out
+      🚪 Log out
    </span>
  </a>
  
@@ -470,7 +470,16 @@
        <li class="md-nav__item">
  <a href="#token-lifecycle-quick-reference" class="md-nav__link">
    <span class="md-ellipsis">
-      Token lifecycle quick reference
+      🧭 Token lifecycle quick reference
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#read-next" class="md-nav__link">
+    <span class="md-ellipsis">
+      📚 Read Next
    </span>
  </a>
  
@@ -566,10 +575,11 @@



-<h1 id="how-to-use">How to Use</h1>
+<h1 id="how-to-use">🖥️ How to Use</h1>
 <p>This page covers the plain HTTP usage of the auth server: creating users,
 logging in, and calling protected endpoints with a bearer token.</p>
-<h2 id="register-a-user">Register a user</h2>
+<hr />
+<h2 id="register-a-user">👤 Register a user</h2>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
 <span class="normal"><a href="#__codelineno-0-2">2</a></span>
 <span class="normal"><a href="#__codelineno-0-3">3</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a>curl<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span>http://localhost:8000/register<span class="w"> </span><span class="se">\</span>
@@ -593,7 +603,8 @@ logging in, and calling protected endpoints with a bearer token.</p>
 </span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5"></a><span class="p">}</span>
 </span></code></pre></div></td></tr></table></div>
 <p>The password is never returned.</p>
-<h2 id="log-in-to-get-a-token">Log in to get a token</h2>
+<hr />
+<h2 id="log-in-to-get-a-token">🔑 Log in to get a token</h2>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-2-1">1</a></span>
 <span class="normal"><a href="#__codelineno-2-2">2</a></span>
 <span class="normal"><a href="#__codelineno-2-3">3</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1"></a>curl<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span>http://localhost:8000/login<span class="w"> </span><span class="se">\</span>
@@ -618,7 +629,8 @@ logging in, and calling protected endpoints with a bearer token.</p>
 </span><span id="__span-3-8"><a id="__codelineno-3-8" name="__codelineno-3-8"></a><span class="p">}</span>
 </span></code></pre></div></td></tr></table></div>
 <p>Invalid credentials return <code>401</code> with <code>{"detail": "Invalid credentials"}</code>.</p>
-<h2 id="call-a-protected-endpoint">Call a protected endpoint</h2>
+<hr />
+<h2 id="call-a-protected-endpoint">🔒 Call a protected endpoint</h2>
 <p>Send the token as a bearer token:</p>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-4-1">1</a></span>
 <span class="normal"><a href="#__codelineno-4-2">2</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1"></a>curl<span class="w"> </span>http://localhost:8000/me<span class="w"> </span><span class="se">\</span>
@@ -626,7 +638,8 @@ logging in, and calling protected endpoints with a bearer token.</p>
 </span></code></pre></div></td></tr></table></div>
 <p>Response <code>200 OK</code> with the current user profile. A missing or invalid token
 returns <code>401</code> with <code>WWW-Authenticate: Bearer</code>.</p>
-<h2 id="log-out">Log out</h2>
+<hr />
+<h2 id="log-out">🚪 Log out</h2>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-5-1">1</a></span>
 <span class="normal"><a href="#__codelineno-5-2">2</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1"></a>curl<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span>http://localhost:8000/logout<span class="w"> </span><span class="se">\</span>
 </span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2"></a><span class="w">  </span>-H<span class="w"> </span><span class="s2">&quot;Authorization: Bearer &lt;jwt&gt;&quot;</span>
@@ -635,7 +648,8 @@ returns <code>401</code> with <code>WWW-Authenticate: Bearer</code>.</p>
 discard the token:</p>
 <div class="language-json highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-6-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">&quot;message&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Successfully logged out. Please discard your token on the client.&quot;</span><span class="w"> </span><span class="p">}</span>
 </span></code></pre></div></td></tr></table></div>
-<h2 id="token-lifecycle-quick-reference">Token lifecycle quick reference</h2>
+<hr />
+<h2 id="token-lifecycle-quick-reference">🧭 Token lifecycle quick reference</h2>
 <table>
 <thead>
 <tr>
@@ -675,6 +689,11 @@ discard the token:</p>
 <p>Interactive examples are available in the <strong>API Reference</strong> site (Swagger UI),
 rendered from <code>docs/api/openapi.json</code>.</p>
 <hr />
+<h2 id="read-next">📚 Read Next</h2>
+<ul>
+<li><a href="../01_centralized_auth/">Centralized Auth</a> — the identity model and token contract.</li>
+<li><a href="../03_platform_integration/">Platform Integration</a> — consuming the token in services.</li>
+</ul>



--- a/auth-server/wiki/03_platform_integration/index.html
+++ b/auth-server/wiki/03_platform_integration/index.html
@@ -456,7 +456,7 @@
        <li class="md-nav__item">
  <a href="#path-1-jwtlib-client-py-jwt" class="md-nav__link">
    <span class="md-ellipsis">
-      Path 1: jwtlib client (py-jwt)
+      🧩 Path 1: jwtlib client (py-jwt)
    </span>
  </a>
  
@@ -465,7 +465,7 @@
        <li class="md-nav__item">
  <a href="#path-2-openapi-first-generated-dependencies" class="md-nav__link">
    <span class="md-ellipsis">
-      Path 2: openapi-first generated dependencies
+      🛠️ Path 2: openapi-first generated dependencies
    </span>
  </a>
  
@@ -474,7 +474,7 @@
        <li class="md-nav__item">
  <a href="#the-introspect-contract" class="md-nav__link">
    <span class="md-ellipsis">
-      The /introspect contract
+      📋 The /introspect contract
    </span>
  </a>
  
@@ -483,7 +483,7 @@
        <li class="md-nav__item">
  <a href="#protecting-endpoints-in-fastapi" class="md-nav__link">
    <span class="md-ellipsis">
-      Protecting endpoints in FastAPI
+      🐍 Protecting endpoints in FastAPI
    </span>
  </a>
  
@@ -492,7 +492,16 @@
        <li class="md-nav__item">
  <a href="#golden-rules" class="md-nav__link">
    <span class="md-ellipsis">
-      Golden rules
+      ⚠️ Golden rules
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#read-next" class="md-nav__link">
+    <span class="md-ellipsis">
+      📚 Read Next
    </span>
  </a>
  
@@ -566,10 +575,11 @@



-<h1 id="platform-integration">Platform Integration</h1>
+<h1 id="platform-integration">🔌 Platform Integration</h1>
 <p>This page is for <strong>service authors</strong> wiring authentication into Aetos
 applications. It covers both supported integration paths.</p>
-<h2 id="path-1-jwtlib-client-py-jwt">Path 1: <code>jwtlib</code> client (<code>py-jwt</code>)</h2>
+<hr />
+<h2 id="path-1-jwtlib-client-py-jwt">🧩 Path 1: <code>jwtlib</code> client (<code>py-jwt</code>)</h2>
 <p>Services that depend on the <code>py-jwt</code> library can authenticate requests
 without an OpenAPI generator. Set the auth server base URL:</p>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="nb">export</span><span class="w"> </span><span class="nv">JWT_SERVER</span><span class="o">=</span>http://auth.aetoskia.com
@@ -598,7 +608,8 @@ without an OpenAPI generator. Set the auth server base URL:</p>
 <p>For zero-request validation (offline token decode), <code>jwtlib</code> also exposes the
 token payload helpers used by the auth server itself — see the
 <code>py-jwt</code> documentation.</p>
-<h2 id="path-2-openapi-first-generated-dependencies">Path 2: <code>openapi-first</code> generated dependencies</h2>
+<hr />
+<h2 id="path-2-openapi-first-generated-dependencies">🛠️ Path 2: <code>openapi-first</code> generated dependencies</h2>
 <p>Services declared with an <strong>OpenAPI-first</strong> contract can generate their
 FastAPI dependencies from the spec. Declare a bearer security scheme pointing
 at the auth server:</p>
@@ -617,7 +628,8 @@ at the auth server:</p>
 <p>The generated dependency then POSTs <code>{"token": token}</code> to the introspection
 path and returns the user on <code>active == true</code>, raising <code>401</code> on invalid or
 inactive tokens and <code>503</code> when the auth server is unreachable.</p>
-<h2 id="the-introspect-contract">The <code>/introspect</code> contract</h2>
+<hr />
+<h2 id="the-introspect-contract">📋 The <code>/introspect</code> contract</h2>
 <table>
 <thead>
 <tr>
@@ -647,7 +659,8 @@ inactive tokens and <code>503</code> when the auth server is unreachable.</p>
 <p>The endpoint <strong>always answers <code>200</code></strong> — validity is expressed through
 <code>active</code>. <code>IntrospectResponse</code> never raises, so the caller can act on the
 tri-state (valid / invalid / user missing) without exception handling.</p>
-<h2 id="protecting-endpoints-in-fastapi">Protecting endpoints in FastAPI</h2>
+<hr />
+<h2 id="protecting-endpoints-in-fastapi">🐍 Protecting endpoints in FastAPI</h2>
 <p>For first-party services, mount the auth router's dependency directly:</p>
 <div class="language-python highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-3-1">1</a></span>
 <span class="normal"><a href="#__codelineno-3-2">2</a></span>
@@ -663,7 +676,8 @@ tri-state (valid / invalid / user missing) without exception handling.</p>
 </span><span id="__span-3-6"><a id="__codelineno-3-6" name="__codelineno-3-6"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">profile</span><span class="p">(</span><span class="n">current_user</span><span class="p">:</span> <span class="n">PublicUser</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_current_user</span><span class="p">)):</span>
 </span><span id="__span-3-7"><a id="__codelineno-3-7" name="__codelineno-3-7"></a>    <span class="k">return</span> <span class="n">current_user</span>
 </span></code></pre></div></td></tr></table></div>
-<h2 id="golden-rules">Golden rules</h2>
+<hr />
+<h2 id="golden-rules">⚠️ Golden rules</h2>
 <ol>
 <li><strong>Never trust an unverified token</strong> — always decode through <code>jwtlib</code> or
   introspect before handling the request.</li>
@@ -672,6 +686,11 @@ tri-state (valid / invalid / user missing) without exception handling.</p>
   the <code>jwtlib</code> client so revocation and issuer changes stay centralized.</li>
 </ol>
 <hr />
+<h2 id="read-next">📚 Read Next</h2>
+<ul>
+<li><a href="../02_how_to_use/">How to Use</a> — the plain HTTP flow.</li>
+<li><a href="../04_deployment/">Deployment</a> — environment, Docker, and CI/CD.</li>
+</ul>



--- a/auth-server/wiki/04_deployment/index.html
+++ b/auth-server/wiki/04_deployment/index.html
@@ -478,7 +478,7 @@
        <li class="md-nav__item">
  <a href="#environment-variables" class="md-nav__link">
    <span class="md-ellipsis">
-      Environment variables
+      ⚙️ Environment variables
    </span>
  </a>
  
@@ -487,7 +487,7 @@
        <li class="md-nav__item">
  <a href="#running-locally" class="md-nav__link">
    <span class="md-ellipsis">
-      Running locally
+      💻 Running locally
    </span>
  </a>
  
@@ -496,7 +496,7 @@
        <li class="md-nav__item">
  <a href="#container-image" class="md-nav__link">
    <span class="md-ellipsis">
-      Container image
+      🐳 Container image
    </span>
  </a>
  
@@ -505,7 +505,7 @@
        <li class="md-nav__item">
  <a href="#cicd-drone" class="md-nav__link">
    <span class="md-ellipsis">
-      CI/CD (Drone)
+      🔄 CI/CD (Drone)
    </span>
  </a>
  
@@ -514,7 +514,16 @@
        <li class="md-nav__item">
  <a href="#environments" class="md-nav__link">
    <span class="md-ellipsis">
-      Environments
+      🌍 Environments
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#read-next" class="md-nav__link">
+    <span class="md-ellipsis">
+      📚 Read Next
    </span>
  </a>
  
@@ -566,9 +575,10 @@



-<h1 id="deployment">Deployment</h1>
+<h1 id="deployment">🚀 Deployment</h1>
 <p>How the auth server is configured and shipped.</p>
-<h2 id="environment-variables">Environment variables</h2>
+<hr />
+<h2 id="environment-variables">⚙️ Environment variables</h2>
 <table>
 <thead>
 <tr>
@@ -619,13 +629,15 @@
 </table>
 <p>Credentials and the token secret live in the environment / Deploy secrets —
 see <code>.env.example</code> for the shape. <code>.env</code> is gitignored.</p>
-<h2 id="running-locally">Running locally</h2>
+<hr />
+<h2 id="running-locally">💻 Running locally</h2>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
 <span class="normal"><a href="#__codelineno-0-2">2</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a>cp<span class="w"> </span>.env.example<span class="w"> </span>.env<span class="w">      </span><span class="c1"># fill in MONGO_HOST, JWT_SECRET</span>
 </span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a>uvicorn<span class="w"> </span>main:app<span class="w"> </span>--reload<span class="w"> </span>--port<span class="w"> </span><span class="m">8000</span>
 </span></code></pre></div></td></tr></table></div>
 <p>The health endpoint is available at <code>GET /health</code>.</p>
-<h2 id="container-image">Container image</h2>
+<hr />
+<h2 id="container-image">🐳 Container image</h2>
 <p>The <code>Dockerfile</code> is a multi-stage build on <code>python:3.13-slim</code>:</p>
 <ol>
 <li><strong>Builder</strong> installs <code>requirements.txt</code> from the private pip index using
@@ -634,7 +646,8 @@ see <code>.env.example</code> for the shape. <code>.env</code> is gitignored.</p
   port <code>8000</code>, and runs <code>uvicorn main:app</code>. A <code>HEALTHCHECK</code> curls
   <code>/health</code>.</li>
 </ol>
-<h2 id="cicd-drone">CI/CD (Drone)</h2>
+<hr />
+<h2 id="cicd-drone">🔄 CI/CD (Drone)</h2>
 <p><code>.drone.yml</code> ships on <strong>git tag</strong> events (arm64):</p>
 <ol>
 <li>Resolve the latest tag.</li>
@@ -647,7 +660,8 @@ see <code>.env.example</code> for the shape. <code>.env</code> is gitignored.</p
 <p>The deployed container runs with <code>--restart always</code>, maps host <strong><code>9003</code> →
 <code>8000</code></strong>, resolves <code>private-pi</code> to <code>192.168.1.111</code> for Mongo, and receives
 <code>MONGO_*</code> + <code>JWT_SECRET</code> from secrets.</p>
-<h2 id="environments">Environments</h2>
+<hr />
+<h2 id="environments">🌍 Environments</h2>
 <table>
 <thead>
 <tr>
@@ -671,6 +685,11 @@ see <code>.env.example</code> for the shape. <code>.env</code> is gitignored.</p
 </tbody>
 </table>
 <hr />
+<h2 id="read-next">📚 Read Next</h2>
+<ul>
+<li><a href="../03_platform_integration/">Platform Integration</a> — the <code>/introspect</code> contract.</li>
+<li><a href="../05_development/">Development</a> — local setup, tests, and docs.</li>
+</ul>



--- a/auth-server/wiki/05_development/index.html
+++ b/auth-server/wiki/05_development/index.html
@@ -498,7 +498,7 @@
        <li class="md-nav__item">
  <a href="#repository-layout" class="md-nav__link">
    <span class="md-ellipsis">
-      Repository layout
+      📂 Repository layout
    </span>
  </a>
  
@@ -507,7 +507,7 @@
        <li class="md-nav__item">
  <a href="#setup" class="md-nav__link">
    <span class="md-ellipsis">
-      Setup
+      🔧 Setup
    </span>
  </a>
  
@@ -516,7 +516,7 @@
        <li class="md-nav__item">
  <a href="#tests" class="md-nav__link">
    <span class="md-ellipsis">
-      Tests
+      🧪 Tests
    </span>
  </a>
  
@@ -525,7 +525,7 @@
        <li class="md-nav__item">
  <a href="#regenerating-the-openapi-spec" class="md-nav__link">
    <span class="md-ellipsis">
-      Regenerating the OpenAPI spec
+      📜 Regenerating the OpenAPI spec
    </span>
  </a>
  
@@ -534,7 +534,16 @@
        <li class="md-nav__item">
  <a href="#building-documentation-docforge" class="md-nav__link">
    <span class="md-ellipsis">
-      Building documentation (docforge)
+      📝 Building documentation (docforge)
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#read-next" class="md-nav__link">
+    <span class="md-ellipsis">
+      📚 Read Next
    </span>
  </a>
  
@@ -564,9 +573,10 @@



-<h1 id="development">Development</h1>
+<h1 id="development">🛠️ Development</h1>
 <p>Working on the auth server itself.</p>
-<h2 id="repository-layout">Repository layout</h2>
+<hr />
+<h2 id="repository-layout">📂 Repository layout</h2>
 <table>
 <thead>
 <tr>
@@ -605,7 +615,8 @@
 </tr>
 </tbody>
 </table>
-<h2 id="setup">Setup</h2>
+<hr />
+<h2 id="setup">🔧 Setup</h2>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
 <span class="normal"><a href="#__codelineno-0-2">2</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1"></a>python<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>.venv
 </span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a>.venv/Scripts/pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>requirements.txt
@@ -617,20 +628,23 @@ and the <code>Dockerfile</code>). Core runtime packages:</p>
 <li><code>mongo-ops==0.1.3</code> — MongoDB persistence layer</li>
 <li><code>fastapi</code>, <code>uvicorn</code>, <code>python-jose</code>, <code>passlib</code>, <code>bcrypt</code>, <code>pymongo</code></li>
 </ul>
-<h2 id="tests">Tests</h2>
+<hr />
+<h2 id="tests">🧪 Tests</h2>
 <p>Run the suite (no network or Mongo required — an in-memory mock is used):</p>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1"></a>.venv/Scripts/pytest<span class="w"> </span>--asyncio-mode<span class="o">=</span>auto
 </span></code></pre></div></td></tr></table></div>
 <p>Coverage spans the full HTTP flow: register → login → wrong-password <code>401</code> →
 <code>/me</code> with and without a token → stateless logout.</p>
-<h2 id="regenerating-the-openapi-spec">Regenerating the OpenAPI spec</h2>
+<hr />
+<h2 id="regenerating-the-openapi-spec">📜 Regenerating the OpenAPI spec</h2>
 <p>The committed <code>docs/api/openapi.json</code> is produced offline:</p>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-2-1">1</a></span>
 <span class="normal"><a href="#__codelineno-2-2">2</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1"></a><span class="nb">set</span><span class="w"> </span><span class="nv">MONGO_HOST</span><span class="o">=</span><span class="m">127</span>.0.0.1
 </span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2"></a>python<span class="w"> </span>generate_spec.py
 </span></code></pre></div></td></tr></table></div>
 <p><code>MONGO_HOST</code> only needs to be set for the import; no connection is opened.</p>
-<h2 id="building-documentation-docforge">Building documentation (docforge)</h2>
+<hr />
+<h2 id="building-documentation-docforge">📝 Building documentation (docforge)</h2>
 <p>The site is generated by <a href="https://git.aetoskia.com/aetos/doc-forge"><code>docforge</code></a>
 and served per kind under <code>site/{kind}</code>:</p>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-3-1">1</a></span>
@@ -640,15 +654,21 @@ and served per kind under <code>site/{kind}</code>:</p>
 <span class="normal"><a href="#__codelineno-3-5">5</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1"></a>doc-forge<span class="w"> </span>build<span class="w"> </span><span class="se">\</span>
 </span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2"></a><span class="w">  </span>--api<span class="w"> </span>--openapi-spec<span class="w"> </span>docs/api/openapi.json<span class="w"> </span><span class="se">\</span>
 </span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3"></a><span class="w">  </span>--mkdocs<span class="w"> </span>--wiki<span class="w"> </span><span class="se">\</span>
-</span><span id="__span-3-4"><a id="__codelineno-3-4" name="__codelineno-3-4"></a><span class="w">  </span>--module-is-source<span class="w"> </span>--module<span class="w"> </span>jwt<span class="w"> </span><span class="se">\</span>
+</span><span id="__span-3-4"><a id="__codelineno-3-4" name="__codelineno-3-4"></a><span class="w">  </span>--module<span class="w"> </span>jwt<span class="w"> </span><span class="se">\</span>
 </span><span id="__span-3-5"><a id="__codelineno-3-5" name="__codelineno-3-5"></a><span class="w">  </span>--site-name<span class="w"> </span><span class="s2">&quot;Aetoskia Auth Server&quot;</span>
 </span></code></pre></div></td></tr></table></div>
 <ul>
 <li><code>--api</code> renders <code>openapi.json</code> with Swagger UI.</li>
-<li><code>--mkdocs</code> renders the library reference from <code>jwt</code> docstrings.</li>
+<li><code>--mkdocs</code> renders the library reference from the <code>jwt</code> package docstrings
+  (nested under <code>docs/lib/jwt/</code>, matching <code>docforge.nav.yml</code>).</li>
 <li><code>--wiki</code> builds this wiki.</li>
 <li>Navigation layout is defined in <code>docforge.nav.yml</code>.</li>
 </ul>
+<blockquote>
+<p>The <code>jwt</code> module is rendered <strong>without</strong> <code>--module-is-source</code> so the library
+output stays nested under <code>docs/lib/jwt/</code>, matching the committed
+<code>docs/mkdocs.lib.yml</code> nav.</p>
+</blockquote>
 <p>Preview locally:</p>
 <div class="language-bash highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-4-1">1</a></span>
 <span class="normal"><a href="#__codelineno-4-2">2</a></span>
@@ -657,6 +677,11 @@ and served per kind under <code>site/{kind}</code>:</p>
 </span><span id="__span-4-3"><a id="__codelineno-4-3" name="__codelineno-4-3"></a>doc-forge<span class="w"> </span>serve<span class="w"> </span>--wiki
 </span></code></pre></div></td></tr></table></div>
 <hr />
+<h2 id="read-next">📚 Read Next</h2>
+<ul>
+<li><a href="../04_deployment/">Deployment</a> — environment and CI/CD.</li>
+<li><a href="../02_how_to_use/">How to Use</a> — exercising the service end to end.</li>
+</ul>



--- a/auth-server/wiki/index.html
+++ b/auth-server/wiki/index.html
@@ -70,7 +70,7 @@
    <div data-md-component="skip">
      
        
-        <a href="#aetoskia-auth-server" class="md-skip">
+        <a href="#aetoskia-auth-server-central-identity-for-the-aetos-platform" class="md-skip">
          Skip to content
        </a>
      
@@ -386,18 +386,9 @@
    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
      
        <li class="md-nav__item">
-  <a href="#why-centralize-authentication" class="md-nav__link">
+  <a href="#key-features" class="md-nav__link">
    <span class="md-ellipsis">
-      Why centralize authentication?
-    </span>
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#sections" class="md-nav__link">
-    <span class="md-ellipsis">
-      Sections
+      🚀 Key Features
    </span>
  </a>
  
@@ -406,16 +397,25 @@
        <li class="md-nav__item">
  <a href="#endpoints-at-a-glance" class="md-nav__link">
    <span class="md-ellipsis">
-      Endpoints at a glance
+      ⚡ Endpoints at a Glance
    </span>
  </a>
  
 </li>
      
        <li class="md-nav__item">
-  <a href="#service-identity" class="md-nav__link">
+  <a href="#documentation-structure" class="md-nav__link">
    <span class="md-ellipsis">
-      Service identity
+      📁 Documentation Structure
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related-resources" class="md-nav__link">
+    <span class="md-ellipsis">
+      🔗 Related Resources
    </span>
  </a>
  
@@ -555,52 +555,29 @@



-<h1 id="aetoskia-auth-server">Aetoskia Auth Server</h1>
+<h1 id="aetoskia-auth-server-central-identity-for-the-aetos-platform">🔐 Aetoskia Auth Server — Central Identity for the Aetos Platform</h1>
 <p>The <strong>Aetoskia Auth Server</strong> is the central identity service of the Aetos
 Platform ecosystem. It issues, validates, and introspects short-lived JWT
 access tokens against a single shared user store backed by MongoDB, so every
 service can trust one issuer instead of shipping its own auth logic.</p>
-<h2 id="why-centralize-authentication">Why centralize authentication?</h2>
+<blockquote>
+<p><strong>Doc model:</strong> this wiki is written for humans — how‑to guides, examples,
+and deployment recipes. The authoritative API contracts live in the code
+(GSDFC docstrings) and the interactive OpenAPI reference under <code>docs/api/</code>.</p>
+</blockquote>
+<hr />
+<h2 id="key-features">🚀 Key Features</h2>
 <ul>
-<li><strong>Single source of identity</strong> — one user database, one issuer, one secret.</li>
-<li><strong>Uniform token contract</strong> — every service verifies the same HS256 JWT.</li>
-<li><strong>No auth code duplication</strong> — services delegate with <code>jwtlib</code> or a
-  generated OpenAPI dependency.</li>
-<li><strong>Instant revocation surface</strong> — introspection gives services a live
-  <code>active</code> check rather than trusting expiry alone.</li>
+<li>🔑 <strong>Centralized identity</strong> — one user database, one issuer, one secret</li>
+<li>🎟️ <strong>Uniform token contract</strong> — every service verifies the same HS256 JWT</li>
+<li>🧩 <strong>No auth code duplication</strong> — services delegate with <code>jwtlib</code> or a
+  generated OpenAPI dependency</li>
+<li>⚡ <strong>Instant revocation surface</strong> — <code>/introspect</code> gives services a live
+  <code>active</code> check rather than trusting expiry alone</li>
+<li>🔓 <strong>Stateless logout</strong> — no server-side sessions; the client discards the token</li>
 </ul>
-<h2 id="sections">Sections</h2>
-<table>
-<thead>
-<tr>
-<th>Section</th>
-<th>What you'll find</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td><a href="01_centralized_auth/">Centralized Auth</a></td>
-<td>The identity model and how the ecosystem trusts the server</td>
-</tr>
-<tr>
-<td><a href="02_how_to_use/">How to Use</a></td>
-<td>Register, login, and call endpoints with tokens</td>
-</tr>
-<tr>
-<td><a href="03_platform_integration/">Platform Integration</a></td>
-<td>How services authenticate requests</td>
-</tr>
-<tr>
-<td><a href="04_deployment/">Deployment</a></td>
-<td>Environment, Docker, and CI/CD</td>
-</tr>
-<tr>
-<td><a href="05_development/">Development</a></td>
-<td>Local setup, tests, and regenerating the spec</td>
-</tr>
-</tbody>
-</table>
-<h2 id="endpoints-at-a-glance">Endpoints at a glance</h2>
+<hr />
+<h2 id="endpoints-at-a-glance">⚡ Endpoints at a Glance</h2>
 <table>
 <thead>
 <tr>
@@ -642,13 +619,47 @@ service can trust one issuer instead of shipping its own auth logic.</p>
 </tr>
 </tbody>
 </table>
-<h2 id="service-identity">Service identity</h2>
+<hr />
+<h2 id="documentation-structure">📁 Documentation Structure</h2>
+<table>
+<thead>
+<tr>
+<th>Section</th>
+<th>What you'll find</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><a href="01_centralized_auth/">Centralized Auth</a></td>
+<td>The identity model and how the ecosystem trusts the server</td>
+</tr>
+<tr>
+<td><a href="02_how_to_use/">How to Use</a></td>
+<td>Register, login, and call endpoints with tokens</td>
+</tr>
+<tr>
+<td><a href="03_platform_integration/">Platform Integration</a></td>
+<td>How services authenticate requests</td>
+</tr>
+<tr>
+<td><a href="04_deployment/">Deployment</a></td>
+<td>Environment, Docker, and CI/CD</td>
+</tr>
+<tr>
+<td><a href="05_development/">Development</a></td>
+<td>Local setup, tests, and regenerating docs</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="related-resources">🔗 Related Resources</h2>
 <ul>
-<li><strong>Title:</strong> Aetoskia Auth Server</li>
-<li><strong>Version:</strong> 0.0.5</li>
-<li><strong>API spec:</strong> <code>docs/api/openapi.json</code> (rendered in the API reference site)</li>
+<li><strong>Source Code:</strong> <a href="https://git.aetoskia.com/aetos/auth-server">Gitea Repository</a></li>
+<li><strong>API Reference:</strong> interactive Swagger UI rendered from <code>docs/api/openapi.json</code></li>
+<li><strong>CI/CD:</strong> Drone pipeline ships tagged releases as <code>aetos/auth-server</code> images</li>
 </ul>
 <hr />
+<p>© Aetoskia Internal — <code>auth-server</code> 0.0.5</p>



--- a/auth-server/wiki/search/search_index.json
+++ b/auth-server/wiki/search/search_index.json
--- a/auth-server/wiki/sitemap.xml.gz
+++ b/auth-server/wiki/sitemap.xml.gz