docs(onboarding): refresh hexa kit — YouTube→emotion pipeline, dual tokens, docs links

Refreshed the onboarding template (rendered PDF is gitignored, carries live tokens):
- ✨ NEW §3 "The YouTube → emotion pipeline": /sources fetch → /jobs poll →
  /artifacts download → /analyze/emotion, the showcase end-to-end flow (curl + the
  @nech/api TS shape), idempotent-on-repeat noted.
- Credentials block now carries BOTH tokens: the api:* Bearer AND the npm read
  token for installing @nech/api from npm.nech.pl.
- Endpoint table gains /sources, /jobs/{id} (+DELETE), /artifacts/{cid}/{name}.
- §1 surfaces the live /docs + /openapi.json links and corrects "access": only
  /healthz is public now; docs/spec need api:docs (covered by api:*).
- Sections renumbered (pipeline=3, client=4, good-to-know=5, support=6).

armada/api/clients/onboarding.html

@@ -61,10 +61,12 @@
   clip, get JSON. Identical audio is cached server-side, so repeats are free.</p>
 
   <div class="cred">
-    <div class="k">Your API key — keep it secret</div>
+    <div class="k">Your API key (Bearer) — scope <span class="mono">api:*</span></div>
     <div class="tok mono">__NECHPL_TOKEN__</div>
-    <div class="warn">Send only over a private channel. Anyone with this key can call the API as you.
-      Lost/leaked? Ping ParVagues and it's revoked &amp; reissued in seconds.</div>
+    <div class="k" style="margin-top:9pt">Your npm read token — to install <span class="mono">@nech/api</span> from <span class="mono">npm.nech.pl</span></div>
+    <div class="tok mono">__NECH_NPM_TOKEN__</div>
+    <div class="warn">Keep both secret — send only over a private channel. Anyone with the API key can call the API as you.
+      Lost/leaked? Ping ParVagues and they're revoked &amp; reissued in seconds.</div>
   </div>
 
   <h2>1 · Talk to it</h2>
@@ -79,7 +81,17 @@
       </ul>
       <h3>Your access</h3>
       <p>Your key carries scope <span class="chip mono">api:*</span> — full access to every
-      Nech.PL API, present and future. Health checks, the spec, and docs are public (no key).</p>
+      Nech.PL API, present and future. Only <span class="mono">/healthz</span> is public; the
+      interactive docs &amp; spec need an <span class="mono">api:docs</span> scope, which your
+      <span class="mono">api:*</span> key already covers.</p>
+      <h3>📖 Docs &amp; spec (live)</h3>
+      <ul>
+        <li>Swagger UI: <span class="mono">https://api.nech.pl/audio/v1/docs</span></li>
+        <li>OpenAPI JSON: <span class="mono">https://api.nech.pl/audio/v1/openapi.json</span></li>
+      </ul>
+      <p class="sub">Both are bearer-gated — open them with your key (e.g. a browser
+      extension that sends <span class="mono">Authorization: Bearer</span>, or
+      <span class="mono">curl -H</span>). Generate a client in any language from the spec.</p>
     </div>
     <div>
       <h3>First call (curl)</h3>
@@ -110,14 +122,36 @@ curl -H <span class="s">"Authorization: Bearer $KEY"</span> \
     <tr><td><span class="mono">POST /spectrum</span></td><td>downsampled spectrogram, bands×frames 0–1 (FFT-as-a-service)</td></tr>
     <tr><td><span class="mono">POST /loudness</span></td><td>BS.1770 LUFS + sample/true peak + gain-to-target (−14/−9)</td></tr>
     <tr><td><span class="mono">POST /naming</span></td><td>convention-compliant sample name from the measured role</td></tr>
+    <tr><td><span class="mono">POST /sources</span></td><td>fetch a URL's audio (yt-dlp) → 44.1k WAV, as a job → <span class="chip">202</span> <span class="mono">{job_id}</span>. ✨ the front door of the YouTube→emotion pipeline</td></tr>
+    <tr><td><span class="mono">GET&nbsp; /jobs/{id}</span> · <span class="mono">DELETE</span></td><td>poll an async job (status/progress/result) · cancel it</td></tr>
+    <tr><td><span class="mono">GET&nbsp; /artifacts/{cid}/{name}</span></td><td>download a stored artifact (fetched source WAV; later stems/loops). Range-capable</td></tr>
     <tr><td><span class="mono">POST /separate</span></td><td><span class="chip">503</span> stem separation — GPU runner pending; code against it now</td></tr>
     <tr><td><span class="mono">GET&nbsp; /healthz</span></td><td>public: liveness probe (no token)</td></tr>
     <tr><td><span class="mono">GET&nbsp; /docs · /openapi.json</span></td><td>interactive docs · spec — need an <span class="mono">api:docs</span> scope (your <span class="mono">api:*</span> token covers it)</td></tr>
   </table>
-  <p class="sub">Interactive docs &amp; full schema: <span class="mono">https://api.nech.pl/audio/v1/docs</span>
-   · <span class="mono">/openapi.json</span> (bearer-gated) — generate a client in any language from the spec.</p>
+  <h2>3 · ✨ The YouTube → emotion pipeline</h2>
+  <p>Hand the API a URL — YouTube, SoundCloud, Bandcamp, any <span class="mono">http(s)</span> yt-dlp
+  supports — and read its mood. <span class="mono">/sources</span> fetches + transcodes to WAV as a
+  background job; poll <span class="mono">/jobs/{id}</span>, grab the artifact, run
+  <span class="mono">/analyze/emotion</span>. Re-fetching the same URL is instant (cached server-side).</p>
+<pre>B=https://api.nech.pl/audio/v1 ; H=<span class="s">"Authorization: Bearer $KEY"</span>
+
+<span class="c"># 1 · fetch a URL's audio as a job  ->  202 { job_id }</span>
+JID=$(curl -s -H <span class="s">"$H"</span> -H <span class="s">"Content-Type: application/json"</span> \
+  -d <span class="s">'{"url":"https://youtu.be/&lt;id&gt;"}'</span> $B/<span class="k">sources</span> | jq -r .job_id)
+
+<span class="c"># 2 · poll until done  ->  { content_id, artifact_ref }</span>
+REF=$(curl -s -H <span class="s">"$H"</span> $B/<span class="k">jobs</span>/$JID | jq -r .result.artifact_ref)
+
+<span class="c"># 3 · download the WAV   4 · read its emotion</span>
+curl -s -H <span class="s">"$H"</span> $B/<span class="k">artifacts</span>/$REF -o src.wav
+curl -s -H <span class="s">"$H"</span> -F file=@src.wav $B/<span class="k">analyze/emotion</span> | jq .emotion
+<span class="c"># -> { valence: 0.62, arousal: 0.78, top: ["energetic","uplifting", …] }</span></pre>
+  <p class="sub">Same pipeline in TypeScript with <span class="mono">@nech/api</span>:
+  <span class="mono">submitSource → getJob (poll) → fetch artifact → analyzeEmotion</span>.
+  Heavier engines (<span class="mono">/separate</span> stems, loops) follow the same job shape.</p>
 
-  <h2>3 · TypeScript / Vercel — <span class="mono">@nech/api</span> (generated)</h2>
+  <h2>4 · TypeScript / Vercel — <span class="mono">@nech/api</span> (generated)</h2>
   <p>The official client is generated from the OpenAPI spec, so it never drifts. Install from the
   private registry (needs your npm read token), then import the per-API subpath — runs on Node 18+,
   Vercel Functions and the Edge.</p>
@@ -139,7 +173,7 @@ curl -H <span class="s">"Authorization: Bearer $KEY"</span> \
 
   <div class="two">
     <div>
-      <h2>4 · Good to know</h2>
+      <h2>5 · Good to know</h2>
       <ul>
         <li><b>Caching is your friend.</b> Same bytes → same result, served instantly. Hash-addressed; nothing to manage.</li>
         <li><b>Limits.</b> Uploads up to ~40&nbsp;MB; a burst rate-limit + monthly quota apply (generous — ask if you hit them).</li>
@@ -149,7 +183,7 @@ curl -H <span class="s">"Authorization: Bearer $KEY"</span> \
       </ul>
     </div>
     <div>
-      <h2>5 · Support</h2>
+      <h2>6 · Support</h2>
       <p>This is hand-built by <b>ParVagues</b> for the hydra-live-hexa Studio. Anything weird,
       a number that looks off, an endpoint you wish existed — just shout. Fast iterations,
       that's the point.</p>