refactor(douanier): scrub the internal codename from the client surface

"Douanier" is the internal codename for the audio sub-API; it shouldn't be what
a consumer imports. Renamed the client-facing surface to the platform brand
(NechAPI), keeping "Douanier" only as the internal service/repo name.

- clients/nech.ts (was douanier.ts) — ONE umbrella `NechAPI` client, namespaced
  per sub-API: `new NechAPI({token}).audio.emotion(clip)`. Future sub-APIs add
  `nech.geo.…` with no import change. Also exports the standalone `NechAudio`
  sub-client for the smaller-bundle path. DouanierError→NechError,
  DouanierOptions→NechOptions. Typechecks clean under tsc --strict.
- response header X-Douanier-Cache → X-Nech-Cache (app.py + all tests + client +
  docs). Verified live end-to-end: miss→hit, old header gone.
- clients/README + onboarding.html (the Shipow PDF source) updated to NechAPI /
  nech.audio. PDF re-rendered.

Built + redeployed douanier:latest to erable; 67 tests green. NOTE (next
iteration): OpenAPI info.title and /healthz `service` still say "douanier" — a
cosmetic /docs leak, scrub on the next redeploy.

armada/api/README.md

@@ -65,7 +65,7 @@ Endpoints (internal root paths shown; public = `/audio/v1` + path):
 - `POST /separate` — stem separation; **503 `compute_unavailable`** until a GPU runner (scope `separate`)
 
 All three analyze routes are **torch-free** (librosa) and **content-addressed
-cached** (#26): the same clip recomputes once, then serves `X-Douanier-Cache: hit`.
+cached** (#26): the same clip recomputes once, then serves `X-Nech-Cache: hit`.
 - `GET  /docs` — Swagger UI
 
 ```bash
@@ -107,7 +107,7 @@ cd armada/api && ~/.virtualenvs/douanier/bin/python -m pytest tests/ -q
 ## Status
 
 Done: scaffold + emotion endpoint (#22/#36), content-addressed cache (#26) — a
-repeat clip returns in ~2 ms (measured 5663× on a real run; `X-Douanier-Cache:
+repeat clip returns in ~2 ms (measured 5663× on a real run; `X-Nech-Cache:
 hit`), **torch-free light V/A engine + CPU Docker image + platform contract
 (`/audio/v1`, central-auth headers, `/metrics`, `/separate` 503) (#37)**. The
 image is ~1 GB and the SRE edge is live and waiting.

armada/api/app.py

@@ -184,7 +184,7 @@ async def _read_upload(file: UploadFile) -> bytes:
 
 
 def _cached(kind: str, params: dict, data: bytes, filename: str, compute, response: Response):
-    """Content-address the bytes, serve a cache hit instantly (X-Douanier-Cache:
+    """Content-address the bytes, serve a cache hit instantly (X-Nech-Cache:
     hit), else run `compute(path)` and cache it. Returns (content_id, result).
     The same engine call is paid ONCE per (content_id, params) — the margin lever."""
     suffix = Path(filename or "clip").suffix or ".wav"
@@ -194,14 +194,14 @@ def _cached(kind: str, params: dict, data: bytes, filename: str, compute, respon
         cid = cache.content_id(tmp.name)
         hit = cache.get(cid, kind, params)
         if hit:
-            response.headers["X-Douanier-Cache"] = "hit"
+            response.headers["X-Nech-Cache"] = "hit"
             return cid, hit["result"]
         try:
             result = compute(tmp.name)
         except Exception as e:
             raise HTTPException(422, f"{kind} analysis failed: {e}")
     cache.put(cid, kind, result=result, params=params)
-    response.headers["X-Douanier-Cache"] = "miss"
+    response.headers["X-Nech-Cache"] = "miss"
     return cid, result
 
 

armada/api/clients/README.md

-# Calling Douanier (the nech.pl `audio` API)
+# Calling the Nech.PL APIs — `audio`
 
 Base URL: **`https://api.nech.pl/audio/v1`** · Auth: **`Authorization: Bearer <token>`**
-(your platform token, provisioned by SRE for your tenant). Interactive docs +
+(your platform token, provisioned for your tenant). Interactive docs +
 schema: `https://api.nech.pl/audio/v1/docs` · `…/openapi.json` (snapshot:
 [`openapi.json`](./openapi.json)).
 
 Every analysis is a `multipart` POST with one `file` field (an audio clip) and
-returns JSON. Identical audio is **cached** — the `X-Douanier-Cache: hit|miss`
+returns JSON. Identical audio is **cached** — the `X-Nech-Cache: hit|miss`
 header (and `result._cache` in the TS client) tells you which.
 
 ## TypeScript client (zero deps)
 
-Drop [`douanier.ts`](./douanier.ts) into your project (Node 18+, Vercel
-Functions, or Edge — it only uses global `fetch`/`FormData`/`Blob`).
+Drop [`nech.ts`](./nech.ts) into your project (Node 18+, Vercel Functions, or
+Edge — it only uses global `fetch`/`FormData`/`Blob`). One umbrella client,
+namespaced per sub-API (`nech.audio.…`, and `nech.geo.…` when it ships):
 
 ```ts
-import { Douanier } from "./douanier";
+import { NechAPI } from "./nech";
 
-const dz = new Douanier({ token: process.env.DOUANIER_TOKEN! });
+const nech = new NechAPI({ token: process.env.NECHPL_TOKEN! });
 
 // a clip from anywhere → a Blob
 const clip = await fetch(trackUrl).then(r => r.blob());
 
-const mood = await dz.emotion(clip);     // { emotion: { valence, arousal, top, … } }
-const spec = await dz.spectrum(clip, { bands: 64, frames: 200 });  // FFT-as-a-service
-const wave = await dz.waveform(clip, { bins: 800 });               // render-ready envelope
-const loud = await dz.loudness(clip);    // { lufs_integrated, gain_to_target_db, … }
+const mood = await nech.audio.emotion(clip);     // { emotion: { valence, arousal, top, … } }
+const spec = await nech.audio.spectrum(clip, { bands: 64, frames: 200 });  // FFT-as-a-service
+const wave = await nech.audio.waveform(clip, { bins: 800 });               // render-ready envelope
+const loud = await nech.audio.loudness(clip);    // { lufs_integrated, gain_to_target_db, … }
 if (mood._cache === "hit") { /* came free from the cache */ }
 ```
 
+Want a smaller bundle? Import just the sub-client:
+```ts
+import { NechAudio } from "./nech";
+const audio = new NechAudio({ token: process.env.NECHPL_TOKEN! });
+const mood = await audio.emotion(clip);
+```
+
 ### Vercel Function example
 
 ```ts
 // app/api/mood/route.ts  (Next.js App Router, Node runtime)
-import { Douanier } from "@/lib/douanier";
+import { NechAPI } from "@/lib/nech";
 
 export async function POST(req: Request) {
   const clip = await req.blob();
-  const dz = new Douanier({ token: process.env.DOUANIER_TOKEN! });
-  const { emotion } = await dz.emotion(clip);
+  const nech = new NechAPI({ token: process.env.NECHPL_TOKEN! });
+  const { emotion } = await nech.audio.emotion(clip);
   return Response.json(emotion);
 }
 ```
@@ -87,5 +95,5 @@ npx @openapitools/openapi-generator-cli generate \
   -i armada/api/clients/openapi.json -g typescript-fetch -o ./generated
 ```
 
-The hand-written `douanier.ts` is the lean, dependency-free alternative — prefer
+The hand-written `nech.ts` is the lean, dependency-free alternative — prefer
 it unless you specifically want generated models.

armada/api/clients/douanier.ts → armada/api/clients/nech.ts

 /**
- * Douanier — typed client for the nech.pl `audio` API.
+ * NechAPI — typed client for the Nech.PL APIs platform (api.nech.pl).
  *
  * Zero dependencies: uses the global `fetch` / `FormData` / `Blob` available in
- * Node 18+, Vercel Functions, and the Edge runtime. Every analysis takes an
- * audio clip (a `Blob` — e.g. from `await fetch(url).then(r => r.blob())`, or a
- * `File` from an upload) and returns a typed JSON result. Identical audio is
- * cached server-side: check `result._cache === "hit"`.
+ * Node 18+, Vercel Functions, and the Edge runtime.
  *
- *   const dz = new Douanier({ token: process.env.DOUANIER_TOKEN! });
- *   const mood = await dz.emotion(clip);          // { valence, arousal, top, … }
- *   const spec = await dz.spectrum(clip, { bands: 64, frames: 200 });
+ * One client, namespaced per sub-API:
+ *
+ *   import { NechAPI } from "./nech";
+ *   const nech = new NechAPI({ token: process.env.NECHPL_TOKEN! });
+ *   const mood = await nech.audio.emotion(clip);       // { emotion: {…} }
+ *   const spec = await nech.audio.spectrum(clip, { bands: 64, frames: 200 });
+ *   // future sub-APIs add namespaces (nech.geo.…) — your import never changes.
+ *
+ * Prefer a smaller bundle? Import just the sub-client you need:
+ *
+ *   import { NechAudio } from "./nech";
+ *   const audio = new NechAudio({ token });
+ *   const mood = await audio.emotion(clip);
+ *
+ * Every audio call takes a clip (a `Blob` — e.g. `await fetch(url).then(r =>
+ * r.blob())`, or a `File` from an upload) and returns typed JSON. Identical audio
+ * is cached server-side: check `result._cache === "hit"`.
  */
 
-export interface DouanierOptions {
-  /** Platform bearer token (provisioned by SRE for your tenant). */
+export interface NechOptions {
+  /** Platform bearer token (provisioned for your tenant). */
   token: string;
-  /** Defaults to the public gateway path. */
+  /** Platform base; defaults to the public gateway. */
   baseUrl?: string;
   /** Inject a custom fetch (tests / non-standard runtimes). */
   fetchImpl?: typeof fetch;
 }
 
+/** Options for a standalone sub-client; baseUrl is that API's versioned root. */
+export interface SubClientOptions {
+  token: string;
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+}
+
 export type Cache = "hit" | "miss";
 type WithMeta<T> = T & { filename: string; content_id: string; _cache: Cache };
 
@@ -51,18 +69,22 @@ export interface Loudness {
 export interface Spectrum { bands: number; frames: number; mel: boolean; band_hz: number[]; spec: number[][]; duration_s: number; sr: number; engine: string; }
 export interface Naming { suggested_name: string; role: string; character: string; stem: string; lint: string[]; }
 
-export class DouanierError extends Error {
+export class NechError extends Error {
   constructor(public status: number, public detail: unknown) {
-    super(`Douanier ${status}: ${typeof detail === "string" ? detail : JSON.stringify(detail)}`);
+    super(`NechAPI ${status}: ${typeof detail === "string" ? detail : JSON.stringify(detail)}`);
   }
 }
 
-export class Douanier {
+/**
+ * The `audio` sub-API client — usable standalone or via `NechAPI#audio`.
+ * Public path: https://api.nech.pl/audio/v1
+ */
+export class NechAudio {
   private base: string;
   private token: string;
   private f: typeof fetch;
 
-  constructor(opts: DouanierOptions) {
+  constructor(opts: SubClientOptions) {
     this.token = opts.token;
     this.base = (opts.baseUrl ?? "https://api.nech.pl/audio/v1").replace(/\/$/, "");
     this.f = opts.fetchImpl ?? fetch;
@@ -81,8 +103,8 @@ export class Douanier {
       body: form,
     });
     const body = await res.json().catch(() => ({}));
-    if (!res.ok) throw new DouanierError(res.status, (body as any)?.detail ?? body);
-    (body as any)._cache = (res.headers.get("X-Douanier-Cache") as Cache) ?? "miss";
+    if (!res.ok) throw new NechError(res.status, (body as any)?.detail ?? body);
+    (body as any)._cache = (res.headers.get("X-Nech-Cache") as Cache) ?? "miss";
     return body as WithMeta<T>;
   }
 
@@ -104,4 +126,18 @@ export class Douanier {
   naming(clip: Blob, o: { index?: number } = {})       { return this.post<Naming>("/naming", clip, o); }
 }
 
-export default Douanier;
+/**
+ * The umbrella platform client. Sub-APIs hang off it as namespaces; today that's
+ * `nech.audio`, tomorrow `nech.geo`, … — with no change to your import.
+ */
+export class NechAPI {
+  /** The Audio Intelligence API (api.nech.pl/audio/v1). */
+  readonly audio: NechAudio;
+
+  constructor(opts: NechOptions) {
+    const base = (opts.baseUrl ?? "https://api.nech.pl").replace(/\/$/, "");
+    this.audio = new NechAudio({ token: opts.token, baseUrl: `${base}/audio/v1`, fetchImpl: opts.fetchImpl });
+  }
+}
+
+export default NechAPI;

armada/api/clients/onboarding.html

@@ -75,7 +75,7 @@
         <li>Base: <span class="mono">https://api.nech.pl/audio/v1</span></li>
         <li>Header: <span class="mono">Authorization: Bearer &lt;key&gt;</span></li>
         <li>Body: <span class="mono">multipart/form-data</span>, one <span class="mono">file</span> field (audio)</li>
-        <li>Returns: JSON. Cache state in <span class="mono">X-Douanier-Cache: hit|miss</span></li>
+        <li>Returns: JSON. Cache state in <span class="mono">X-Nech-Cache: hit|miss</span></li>
       </ul>
       <h3>Your access</h3>
       <p>Your key carries scope <span class="chip mono">api:*</span> — full access to every
@@ -117,15 +117,16 @@ curl -H <span class="s">"Authorization: Bearer $KEY"</span> \
    · <span class="mono">/openapi.json</span> — generate a client in any language from the spec.</p>
 
   <h2>3 · TypeScript / Vercel (zero deps)</h2>
-  <p>Drop <span class="mono">douanier.ts</span> (ships with this kit) into your project — it uses only
-  global <span class="mono">fetch</span>/<span class="mono">FormData</span>, so it runs on Node 18+, Vercel Functions and the Edge.</p>
-<pre><span class="k">import</span> { Douanier } <span class="k">from</span> <span class="s">"./douanier"</span>;
+  <p>Drop <span class="mono">nech.ts</span> (ships with this kit) into your project — it uses only
+  global <span class="mono">fetch</span>/<span class="mono">FormData</span>, so it runs on Node 18+, Vercel Functions and the Edge.
+  One client, namespaced per API (<span class="mono">nech.audio.…</span>).</p>
+<pre><span class="k">import</span> { NechAPI } <span class="k">from</span> <span class="s">"./nech"</span>;
 
-<span class="k">const</span> dz = <span class="k">new</span> Douanier({ token: process.env.<span class="k">NECHPL_TOKEN</span>! });
+<span class="k">const</span> nech = <span class="k">new</span> NechAPI({ token: process.env.<span class="k">NECHPL_TOKEN</span>! });
 
 <span class="k">const</span> clip = <span class="k">await</span> fetch(trackUrl).then(r =&gt; r.blob());
-<span class="k">const</span> mood = <span class="k">await</span> dz.emotion(clip);    <span class="c">// { emotion: { valence, arousal, top, … } }</span>
-<span class="k">const</span> spec = <span class="k">await</span> dz.spectrum(clip, { bands: 64, frames: 200 });
+<span class="k">const</span> mood = <span class="k">await</span> nech.audio.emotion(clip);  <span class="c">// { emotion: { valence, arousal, … } }</span>
+<span class="k">const</span> spec = <span class="k">await</span> nech.audio.spectrum(clip, { bands: 64, frames: 200 });
 <span class="k">if</span> (mood._cache === <span class="s">"hit"</span>) { <span class="c">/* came free from the cache */</span> }</pre>
 
   <div class="two">

armada/api/tests/test_grade_endpoint.py

@@ -36,14 +36,14 @@ def test_grade_endpoint_and_cache():
     files = {"file": ("loop.wav", _wav_bytes(), "audio/wav")}
     r1 = client.post("/grade", files=files, headers=GW)
     assert r1.status_code == 200
-    assert r1.headers["X-Douanier-Cache"] == "miss"
+    assert r1.headers["X-Nech-Cache"] == "miss"
     g = r1.json()["grade"]
     assert g["tier"] in {"S", "A", "B", "C", "D"}
     assert 0.0 <= g["grade"] <= 1.0
     assert "seam" in g["sub"] and "rms_dbfs" in g["metrics"]
 
     r2 = client.post("/grade", files={"file": ("loop.wav", _wav_bytes(), "audio/wav")}, headers=GW)
-    assert r2.headers["X-Douanier-Cache"] == "hit"
+    assert r2.headers["X-Nech-Cache"] == "hit"
 
 
 def test_grade_scope_enforced():

armada/api/tests/test_signal.py

@@ -70,11 +70,11 @@ GW = lambda scope="*": {"X-Tenant": "hexa", "X-Scopes": "api:audio:*"}
 def test_onsets_endpoint_and_cache():
     files = {"file": ("c.wav", _wav_bytes(_click_track()), "audio/wav")}
     r1 = client.post("/onsets", files=files, headers=GW("onsets"))
-    assert r1.status_code == 200 and r1.headers["X-Douanier-Cache"] == "miss"
+    assert r1.status_code == 200 and r1.headers["X-Nech-Cache"] == "miss"
     assert "onsets" in r1.json() and r1.json()["n_onsets"] >= 3
     r2 = client.post("/onsets", files={"file": ("c.wav", _wav_bytes(_click_track()), "audio/wav")},
                      headers=GW("onsets"))
-    assert r2.headers["X-Douanier-Cache"] == "hit"
+    assert r2.headers["X-Nech-Cache"] == "hit"
 
 
 def test_waveform_endpoint():

armada/api/tests/test_smoke.py

@@ -84,12 +84,12 @@ def test_emotion_happy_path_and_cache(monkeypatch):
 
     r1 = client.post("/analyze/emotion", files=files, headers=GW)
     assert r1.status_code == 200
-    assert r1.headers["X-Douanier-Cache"] == "miss"
+    assert r1.headers["X-Nech-Cache"] == "miss"
     assert r1.json()["emotion"]["valence"] == 0.42
     assert r1.json()["content_id"].startswith(("cid_", "raw_"))
 
     r2 = client.post("/analyze/emotion", files=files, headers=GW)
-    assert r2.headers["X-Douanier-Cache"] == "hit"
+    assert r2.headers["X-Nech-Cache"] == "hit"
     assert calls["n"] == 1            # engine ran ONCE; 2nd served from cache
 
 
@@ -115,13 +115,13 @@ def test_features_endpoint_and_cache():
     files = {"file": ("c.wav", _wav_bytes(), "audio/wav")}
     r1 = client.post("/features", files=files, headers=GW)
     assert r1.status_code == 200
-    assert r1.headers["X-Douanier-Cache"] == "miss"
+    assert r1.headers["X-Nech-Cache"] == "miss"
     body = r1.json()
     assert "features" in body and body["engine"] == "light"
     assert "spectral_centroid" in body["features"]
     r2 = client.post("/features", files={"file": ("c.wav", _wav_bytes(), "audio/wav")},
                      headers=GW)
-    assert r2.headers["X-Douanier-Cache"] == "hit"
+    assert r2.headers["X-Nech-Cache"] == "hit"
 
 
 def test_features_scope_enforced():