diff --git a/middleware/packages/harness-api-key-auth/src/apiKeyToken.ts b/middleware/packages/harness-api-key-auth/src/apiKeyToken.ts
index c62880e8d..5a7ae4e74 100644
--- a/middleware/packages/harness-api-key-auth/src/apiKeyToken.ts
+++ b/middleware/packages/harness-api-key-auth/src/apiKeyToken.ts
@@ -4,9 +4,11 @@
  * any plugin can share the SAME implementation (core must never import from a
  * channel plugin).
  *
- * Mirrors `middleware/src/devplatform/jobToken.ts` (the dev-runner's one-time
- * job token), the closest existing precedent for a bearer credential this
- * codebase hashes at rest and verifies in constant time. The plaintext exists
+ * Follows the shape this codebase already uses for one-time bearer credentials
+ * elsewhere: hashed at rest, verified in constant time, plaintext shown once.
+ * (The path is deliberately not cited — the closest precedent lives in the Dev
+ * Platform, which epic #470 is extracting into its own repository.) The
+ * plaintext exists
  * exactly once — at creation time, returned to the operator — and is never
  * persisted. Only its sha256 hex lands in the vault (`apiKeyStore.ts`).
  * Verification hashes the presented token and compares digests with
@@ -16,7 +18,7 @@
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 
 /** Every minted key carries this prefix so it is greppable in logs/incidents
- *  and visually distinct from other omadia tokens (e.g. `djr_`). */
+ *  and visually distinct from the other prefixed token families omadia mints. */
 export const API_KEY_PREFIX = 'omk_';
 
 /** 32 random bytes → 43 base64url chars; with the prefix, a 47-char key. */
diff --git a/middleware/test/channelApi/apiKeyToken.test.ts b/middleware/test/channelApi/apiKeyToken.test.ts
index 507f28fa9..18306684d 100644
--- a/middleware/test/channelApi/apiKeyToken.test.ts
+++ b/middleware/test/channelApi/apiKeyToken.test.ts
@@ -12,9 +12,10 @@ import {
 } from '../../packages/harness-api-key-auth/src/apiKeyToken.js';
 
 /**
- * Issue #438 — pure-unit coverage for the API-key token, mirroring
- * `test/devplatform/jobToken.test.ts` (the closest existing precedent for a
- * hashed, constant-time-verified bearer credential in this codebase).
+ * Issue #438 — pure-unit coverage for the API-key token, following the coverage
+ * shape this codebase already uses for hashed, constant-time-verified bearer
+ * credentials: prefix and entropy, hash-only persistence, and a verify path
+ * that rejects on any mismatch without leaking timing.
  */
 describe('channelApi/apiKeyToken', () => {
   it('mints `omk_` + 32 random bytes base64url, and stores only the sha256 hex', () => {