dominus-sdk-nodejs 11.0.3 → 11.0.5

package/docs/agent-guide/2026-06-27-0849-sdk-orient/10-agent-playbook.md

@@ -1,48 +1,48 @@
-# 10 Agent Playbook
-
-## If You Are Changing X, Read Y First
-
-- **A namespace command** → `src/namespaces/<name>.ts` + the relevant rows in
-  `docs/routes-services.md`. Follow the Public API Change Checklist in
-  `CLAUDE.md` (update namespace, wire in `src/index.ts` if new, export types,
-  update `docs/usage-reference.md` and `routes-services.md`).
-- **Transport / auth / retries / streaming / binary** → `src/lib/client.ts` and
-  `docs/architecture.md` §3,§5,§6,§7. The 55-min JWT cache TTL is load-bearing;
-  do not regress it without raising the jwt-worker `JWT_EXPIRY_SECONDS` first.
-- **A new public type or root shortcut** → `src/index.ts` (constructor + export).
-- **Errors** → `src/lib/errors.ts`; pass `endpoint` on service-auth throws so
-  callers can classify by `DominusError.endpoint`.
-- **Env/gateway config** → `src/lib/config.ts`.
-
-## If Validation Fails
-
-- Build/type errors → `npm run typecheck`; the repo's lint IS tsc.
-- Type-contract failures → `npm run test:types` (the `*.typecheck.ts` files).
-- Unit/contract failures → `npm test` runs an explicit file list; run a single
-  file with `node --test tests/<file>.test.js` after `npm run build`.
-
-## Common Traps
-
-- Importing from a subpath — there is only one export entry; import from
-  `'dominus-sdk-nodejs'`.
-- Treating `dist/` as source — it is generated; edit `src/`.
-- Forgetting the version bump — publish-production no-ops if the version already
-  exists on npm.
-- Using `dominus-production` as this repo's branch — it is `production` here.
-- Pointing `browser` methods at worker-local `/runs/*` — use `/api/browser/*`
-  with `useGateway: true`.
-
-## Which Kyle Skill For Common Work
-
-- Behavior change / bug fix → `kyle-fix` (test-first via `kyle-tdd`).
-- Root-cause unknown → `kyle-diagnose`.
-- Plan a larger change → `kyle-plan`.
-- Review a diff → `kyle-review`.
-- Contract-sensitive change (wire protocol, JWT, routing) → route to
-  `dominus-expert` before shipping.
-- Docs/cleanup drift → `kyle-janitor` (this pack).
-
-## Handoff Expectations
-
-This is a Dominus platform repo: cross-contract or wire-protocol changes need
-`dominus-expert` review. Releases are npm publishes gated on a version bump.
+# 10 Agent Playbook
+
+## If You Are Changing X, Read Y First
+
+- **A namespace command** → `src/namespaces/<name>.ts` + the relevant rows in
+  `docs/routes-services.md`. Follow the Public API Change Checklist in
+  `CLAUDE.md` (update namespace, wire in `src/index.ts` if new, export types,
+  update `docs/usage-reference.md` and `routes-services.md`).
+- **Transport / auth / retries / streaming / binary** → `src/lib/client.ts` and
+  `docs/architecture.md` §3,§5,§6,§7. The 55-min JWT cache TTL is load-bearing;
+  do not regress it without raising the jwt-worker `JWT_EXPIRY_SECONDS` first.
+- **A new public type or root shortcut** → `src/index.ts` (constructor + export).
+- **Errors** → `src/lib/errors.ts`; pass `endpoint` on service-auth throws so
+  callers can classify by `DominusError.endpoint`.
+- **Env/gateway config** → `src/lib/config.ts`.
+
+## If Validation Fails
+
+- Build/type errors → `npm run typecheck`; the repo's lint IS tsc.
+- Type-contract failures → `npm run test:types` (the `*.typecheck.ts` files).
+- Unit/contract failures → `npm test` runs an explicit file list; run a single
+  file with `node --test tests/<file>.test.js` after `npm run build`.
+
+## Common Traps
+
+- Importing from a subpath — there is only one export entry; import from
+  `'dominus-sdk-nodejs'`.
+- Treating `dist/` as source — it is generated; edit `src/`.
+- Forgetting the version bump — publish-production no-ops if the version already
+  exists on npm.
+- Using `dominus-production` as this repo's branch — it is `production` here.
+- Pointing `browser` methods at worker-local `/runs/*` — use `/api/browser/*`
+  with `useGateway: true`.
+
+## Which Kyle Skill For Common Work
+
+- Behavior change / bug fix → `kyle-fix` (test-first via `kyle-tdd`).
+- Root-cause unknown → `kyle-diagnose`.
+- Plan a larger change → `kyle-plan`.
+- Review a diff → `kyle-review`.
+- Contract-sensitive change (wire protocol, JWT, routing) → route to
+  `dominus-expert` before shipping.
+- Docs/cleanup drift → `kyle-janitor` (this pack).
+
+## Handoff Expectations
+
+This is a Dominus platform repo: cross-contract or wire-protocol changes need
+`dominus-expert` review. Releases are npm publishes gated on a version bump.

package/docs/agent-guide/2026-08-04-sdk-nodejs/00-reading-order.md

@@ -1,11 +1,11 @@
-# Dominus SDK for Node.js — reading order
-
-Snapshot: 2026-08-04, production source commit `0e68c79`.
-
-1. `README.md` for package usage, namespace coverage, and lifecycle guidance.
-2. `package.json` for the single export entry and release scripts.
-3. `src/index.ts` and namespace modules for the public surface.
-4. `src/client.ts`/transport and typed error helpers for gateway behavior.
-5. `tests/` plus `tsconfig.type-tests.json` for runtime and compile contracts.
-6. `.github/workflows/publish-production.yml` for registry publication.
-7. `docs/atlas/2026-08-04-sdk-nodejs-truthmap.md` and the pending-work summary.
+# Dominus SDK for Node.js — reading order
+
+Snapshot: 2026-08-04, production source commit `0e68c79`.
+
+1. `README.md` for package usage, namespace coverage, and lifecycle guidance.
+2. `package.json` for the single export entry and release scripts.
+3. `src/index.ts` and namespace modules for the public surface.
+4. `src/client.ts`/transport and typed error helpers for gateway behavior.
+5. `tests/` plus `tsconfig.type-tests.json` for runtime and compile contracts.
+6. `.github/workflows/publish-production.yml` for registry publication.
+7. `docs/atlas/2026-08-04-sdk-nodejs-truthmap.md` and the pending-work summary.

package/docs/agent-guide/2026-08-04-sdk-nodejs/01-purpose-and-boundaries.md

@@ -1,14 +1,14 @@
-# Purpose and boundaries
-
-The Node SDK is the typed ESM facade for Dominus gateway-first services. It
-packages namespace APIs for application auth, data/DDL, storage and Artifact
-V2, AI/runtime, browser automation, jobs, workflows, Authority, logs,
-platform/coder, Publisher, admin, and control-plane operations.
-
-The package owns client-side request shaping, gateway route transforms,
-service error decoding, and public type contracts. Server-side authorization,
-scope truth, lifecycle truth, and durable records remain owned by the relevant
-Dominus services.
-
-The supported package surface is the single root export. Internal source files
-are not stable subpath imports.
+# Purpose and boundaries
+
+The Node SDK is the typed ESM facade for Dominus gateway-first services. It
+packages namespace APIs for application auth, data/DDL, storage and Artifact
+V2, AI/runtime, browser automation, jobs, workflows, Authority, logs,
+platform/coder, Publisher, admin, and control-plane operations.
+
+The package owns client-side request shaping, gateway route transforms,
+service error decoding, and public type contracts. Server-side authorization,
+scope truth, lifecycle truth, and durable records remain owned by the relevant
+Dominus services.
+
+The supported package surface is the single root export. Internal source files
+are not stable subpath imports.

package/docs/agent-guide/2026-08-04-sdk-nodejs/03-api-surface.md

@@ -1,16 +1,16 @@
-# API surface
-
-Import from the root package:
-
-```ts
-import { dominus } from 'dominus-sdk-nodejs';
-```
-
-The singleton exposes namespace groups including `auth`, `db`, `ddl`, `files`,
-`stash`, `ai`, `browser`, `jobs`, `workflow`, `authority`, `logs`, `platform`,
-`coder`, `publisher`, `admin`, and control-plane helpers. The exact exported
-types are generated by `npm run build` from `src/`.
-
-`workflow.ensure` is the preferred Authority-backed lifecycle entry. Use the
-Authority namespace for run timeline truth and the explicit archive/repair
-helpers for proof-first maintenance.
+# API surface
+
+Import from the root package:
+
+```ts
+import { dominus } from 'dominus-sdk-nodejs';
+```
+
+The singleton exposes namespace groups including `auth`, `db`, `ddl`, `files`,
+`stash`, `ai`, `browser`, `jobs`, `workflow`, `authority`, `logs`, `platform`,
+`coder`, `publisher`, `admin`, and control-plane helpers. The exact exported
+types are generated by `npm run build` from `src/`.
+
+`workflow.ensure` is the preferred Authority-backed lifecycle entry. Use the
+Authority namespace for run timeline truth and the explicit archive/repair
+helpers for proof-first maintenance.

package/docs/agent-guide/2026-08-04-sdk-nodejs/10-agent-playbook.md

@@ -1,14 +1,14 @@
-# Agent playbook
-
-Before changing an SDK method, trace its route transform, request body, typed
-error contract, and corresponding worker/service endpoint. Run:
-
-```text
-npm run build
-npm run test:types
-npm test
-```
-
-For a package release, update the version intentionally and verify the new
-version is not already published before pushing the `production` lane. A
-local SDK test pass does not prove server or registry state.
+# Agent playbook
+
+Before changing an SDK method, trace its route transform, request body, typed
+error contract, and corresponding worker/service endpoint. Run:
+
+```text
+npm run build
+npm run test:types
+npm test
+```
+
+For a package release, update the version intentionally and verify the new
+version is not already published before pushing the `production` lane. A
+local SDK test pass does not prove server or registry state.

package/docs/agent-guide/INDEX.md

@@ -1,14 +1,14 @@
-# Agent Guide Index
-
-Last updated: 2026-08-04 local
-Current snapshot: `2026-08-04-sdk-nodejs/00-reading-order.md`
-
-## Read Order
-
-1. `2026-08-04-sdk-nodejs/00-reading-order.md`
-2. `2026-08-04-sdk-nodejs/01-purpose-and-boundaries.md`
-3. `2026-08-04-sdk-nodejs/03-api-surface.md`
-4. `2026-08-04-sdk-nodejs/10-agent-playbook.md`
-
-The published package entry point and `src/` remain authoritative. Historical
-guide packs are retained for prior release context.
+# Agent Guide Index
+
+Last updated: 2026-08-04 local
+Current snapshot: `2026-08-04-sdk-nodejs/00-reading-order.md`
+
+## Read Order
+
+1. `2026-08-04-sdk-nodejs/00-reading-order.md`
+2. `2026-08-04-sdk-nodejs/01-purpose-and-boundaries.md`
+3. `2026-08-04-sdk-nodejs/03-api-surface.md`
+4. `2026-08-04-sdk-nodejs/10-agent-playbook.md`
+
+The published package entry point and `src/` remain authoritative. Historical
+guide packs are retained for prior release context.

package/docs/agent-guide/current.md

@@ -1,22 +1,22 @@
-# Current Agent-Guide Snapshot
-
-Latest snapshot: `2026-06-27-0849-sdk-orient/00-reading-order.md`
-
-Generated 2026-06-27 from SDK v6.6.0 (`package.json`) on branch `production`.
-
-## Top Five Facts To Refresh Before Editing
-
-1. **Version + changelog.** Confirm `package.json` `version` and the top of
-   `CHANGELOG.md`; this pack was written at `6.6.0`.
-2. **Namespace count.** `src/namespaces/` had 27 files, each wired as a
-   `public readonly` property in `src/index.ts`. Re-count before claiming a
-   surface is missing.
-3. **Tests exist.** `tests/` has 24 test files run by `npm test`. The older
-   claim in `docs/architecture.md` §10 / `CLAUDE.md` ("no committed tests") was
-   stale and is corrected in this pass.
-4. **Storage rule.** `dominus.stash.*` is the primary storage surface;
-   `redis`/`db`/`files`/`artifacts` are building blocks (see
-   `docs/architecture.md` §2a).
-5. **Release lane.** Push to `production` triggers
-   `.github/workflows/publish-production.yml` (npm publish). Do not commit/push
-   from janitor work.
+# Current Agent-Guide Snapshot
+
+Latest snapshot: `2026-06-27-0849-sdk-orient/00-reading-order.md`
+
+Generated 2026-06-27 from SDK v6.6.0 (`package.json`) on branch `production`.
+
+## Top Five Facts To Refresh Before Editing
+
+1. **Version + changelog.** Confirm `package.json` `version` and the top of
+   `CHANGELOG.md`; this pack was written at `6.6.0`.
+2. **Namespace count.** `src/namespaces/` had 27 files, each wired as a
+   `public readonly` property in `src/index.ts`. Re-count before claiming a
+   surface is missing.
+3. **Tests exist.** `tests/` has 24 test files run by `npm test`. The older
+   claim in `docs/architecture.md` §10 / `CLAUDE.md` ("no committed tests") was
+   stale and is corrected in this pass.
+4. **Storage rule.** `dominus.stash.*` is the primary storage surface;
+   `redis`/`db`/`files`/`artifacts` are building blocks (see
+   `docs/architecture.md` §2a).
+5. **Release lane.** Push to `production` triggers
+   `.github/workflows/publish-production.yml` (npm publish). Do not commit/push
+   from janitor work.

package/docs/architecture.md

@@ -1,119 +1,119 @@
-# SDK Architecture
-
-This document describes how `dominus-sdk-nodejs` is structured and how requests flow from namespace methods to backend services.
-
-## 1. Public Surface
-
-- Entry point: `src/index.ts`
-- Singleton export: `dominus`
-- Public API composition:
-  - Namespace properties (`dominus.auth`, `dominus.db`, `dominus.ai`, ...)
-  - Root shortcuts for common operations (`get`, `upsert`, `listTables`, `queryTable`, `addTable`, etc.)
-  - Utility exports (errors, crypto helpers, cache utilities, JWT helpers)
-
-## 2. Layering
-
-- Namespace layer (`src/namespaces/*`)
-  - Maps method calls to concrete API routes
-  - Translates ergonomic SDK params to backend payload shape
-  - Minimal orchestration and convenience wrappers
-- Transport layer (`src/lib/client.ts`)
-  - Auth token selection (service JWT vs user JWT)
-  - Request encoding/decoding protocol
-  - Retries, timeout handling, circuit breaker checks
-  - SSE streaming and binary upload/download support
-- Support libraries (`src/lib/*`)
-  - `cache.ts`: encrypted in-memory cache + circuit breaker primitives
-  - `errors.ts`: typed SDK errors
-  - `config.ts`: env/config resolution
-  - `console-capture.ts`: optional console forwarding to logs
-  - `page-rules.ts`, `user-session.ts`: local portal/session acceleration
-
-## 2a. Storage layer positioning
-
-`dominus.stash.*` is the **primary storage surface**. Applications store named-kind data through Stash and the kind registry routes each kind to the right backend; callers address data by what it *is* (`kind` + `scope` + `key`), not by which primitive holds it. The primitive namespaces (`redis`, `db`, `files`) and the addressed `artifacts` helpers remain as building blocks — they are not deprecated and are never removed — but they are rarely targeted directly for application data.
-
-This is the **Two-Layer Storage Rule**: applications store named-kind data via Stash; primitives are used directly only for ephemera (locks, queues, cache) or when building a kernel backend.
-
-| Your data | Use | Why |
-|---|---|---|
-| Named, durable data of a registered kind (artifacts, conversations, configs, recipes, secrets) | `dominus.stash.*` | Primary surface; the kind registry routes to the right backend and policy. |
-| A direct `ar://`-addressed artifact workflow (you already hold a canonical ref) | `dominus.artifacts.*` | Escape hatch for explicit Artifact V2 addressing; prefer a Stash `artifact-v2`-backed kind for new code. |
-| Locks, queues, rate counters, short-lived cache — ephemera | `dominus.redis.*` | Building block for ephemeral state; named data belongs in Stash. |
-| Building a new kernel backend or a documented migration fallback | primitives (`redis`, `db`, `files`) | The lowest layer; not the place for ordinary application data. |
-
-## 3. Request Lifecycle
-
-1. Caller invokes namespace method.
-2. Namespace builds request options (`endpoint`, `method`, `body`, `useGateway`, optional `userToken`).
-3. `DominusClient` resolves auth context:
-   - if `userToken` provided: uses caller token
-   - otherwise: ensures service JWT exists (PSK -> `/jwt/mint`, cached)
-4. Request payload is serialized to JSON, then base64-encoded for Dominus wire protocol.
-5. HTTP request is sent.
-6. Response body is decoded from base64 and parsed.
-7. Errors are mapped to SDK error types.
-
-## 4. Routing Model
-
-- Namespace code generally targets `/api/*` endpoints.
-- For methods with `useGateway: true`, client route transform maps `/api/*` to gateway `/svc/*` dispatch paths.
-- Some methods intentionally use direct fetch paths (for example health checks/JWKS fetch).
-
-See [routes-services.md](./routes-services.md) for full route/service assessment.
-
-## 5. Auth and Token Handling
-
-### Service token flow
-
-- Input: `DOMINUS_TOKEN` (PSK)
-- Client exchanges PSK for short-lived JWT via gateway auth route.
-- JWT is cached with refresh buffer and refresh mutex to avoid thundering herd under concurrency.
-
-### User token flow
-
-- Methods that accept `userToken` pass caller JWT through unchanged.
-- Backend performs authorization checks for the user context.
-
-### Local JWT utilities
-
-- `verifyJwtLocally`, `isJwtValid`, and `mintSelectedScopeJwt` are exported from `src/lib/client.ts`. Selected-scope targeting is now the only supported SDK helper vocabulary.
-- `mintSelectedScopeJwt(targetOrgId, targetEnv)` is the canonical selected-scope mint helper; the live `/jwt/mint` contract keys selected scope off org plus environment, not a shared-routing flag.
-- `auth.getJwks` fetches public keys and caches them.
-- `auth.validateJwt` performs local payload checks/expiry validation.
-
-## 6. Caching and Resilience
-
-- Encrypted in-memory cache used for selected short-lived values (JWT, portal/session-related caches).
-- Circuit breaker support exists in transport/cache layer.
-- Retry with backoff is applied for transient request failures and mint flow.
-
-## 7. Streaming and Binary Paths
-
-- SSE: `streamRequest()` in client, used by AI streaming methods.
-- Multipart binary upload: `binaryUpload()`.
-- Binary download to `Buffer`: `binaryDownload()`.
-
-## 8. Speech APIs
-
-Speech routes are owned by agent-runtime through the `dominus.ai` namespace:
-
-- `dominus.ai.stt(audio, options?)` -> `POST /api/agent/stt`
-- `dominus.ai.tts(text, options?)` -> `POST /api/agent/tts`
-
-The legacy streaming STT namespace (`dominus.stt`) is retired in hard cutover.
-
-## 9. Documentation Topology
-
-Canonical documentation set for this repository:
-
-- [README.md](../README.md): overview and usage entry
-- [CLAUDE.md](../CLAUDE.md): agent conventions for this repo
-- [usage-reference.md](./usage-reference.md): exhaustive namespaced command reference
-- [routes-services.md](./routes-services.md): service and endpoint assessment
-
-## 10. Known Gaps
-
-- The hand-maintained command/namespace counts in `routes-services.md` and
-  `usage-reference.md` can drift from source; re-derive from `src/namespaces/*.ts`
-  and `src/index.ts` before quoting them.
+# SDK Architecture
+
+This document describes how `dominus-sdk-nodejs` is structured and how requests flow from namespace methods to backend services.
+
+## 1. Public Surface
+
+- Entry point: `src/index.ts`
+- Singleton export: `dominus`
+- Public API composition:
+  - Namespace properties (`dominus.auth`, `dominus.db`, `dominus.ai`, ...)
+  - Root shortcuts for common operations (`get`, `upsert`, `listTables`, `queryTable`, `addTable`, etc.)
+  - Utility exports (errors, crypto helpers, cache utilities, JWT helpers)
+
+## 2. Layering
+
+- Namespace layer (`src/namespaces/*`)
+  - Maps method calls to concrete API routes
+  - Translates ergonomic SDK params to backend payload shape
+  - Minimal orchestration and convenience wrappers
+- Transport layer (`src/lib/client.ts`)
+  - Auth token selection (service JWT vs user JWT)
+  - Request encoding/decoding protocol
+  - Retries, timeout handling, circuit breaker checks
+  - SSE streaming and binary upload/download support
+- Support libraries (`src/lib/*`)
+  - `cache.ts`: encrypted in-memory cache + circuit breaker primitives
+  - `errors.ts`: typed SDK errors
+  - `config.ts`: env/config resolution
+  - `console-capture.ts`: optional console forwarding to logs
+  - `page-rules.ts`, `user-session.ts`: local portal/session acceleration
+
+## 2a. Storage layer positioning
+
+`dominus.stash.*` is the **primary storage surface**. Applications store named-kind data through Stash and the kind registry routes each kind to the right backend; callers address data by what it *is* (`kind` + `scope` + `key`), not by which primitive holds it. The primitive namespaces (`redis`, `db`, `files`) and the addressed `artifacts` helpers remain as building blocks — they are not deprecated and are never removed — but they are rarely targeted directly for application data.
+
+This is the **Two-Layer Storage Rule**: applications store named-kind data via Stash; primitives are used directly only for ephemera (locks, queues, cache) or when building a kernel backend.
+
+| Your data | Use | Why |
+|---|---|---|
+| Named, durable data of a registered kind (artifacts, conversations, configs, recipes, secrets) | `dominus.stash.*` | Primary surface; the kind registry routes to the right backend and policy. |
+| A direct `ar://`-addressed artifact workflow (you already hold a canonical ref) | `dominus.artifacts.*` | Escape hatch for explicit Artifact V2 addressing; prefer a Stash `artifact-v2`-backed kind for new code. |
+| Locks, queues, rate counters, short-lived cache — ephemera | `dominus.redis.*` | Building block for ephemeral state; named data belongs in Stash. |
+| Building a new kernel backend or a documented migration fallback | primitives (`redis`, `db`, `files`) | The lowest layer; not the place for ordinary application data. |
+
+## 3. Request Lifecycle
+
+1. Caller invokes namespace method.
+2. Namespace builds request options (`endpoint`, `method`, `body`, `useGateway`, optional `userToken`).
+3. `DominusClient` resolves auth context:
+   - if `userToken` provided: uses caller token
+   - otherwise: ensures service JWT exists (PSK -> `/jwt/mint`, cached)
+4. Request payload is serialized to JSON, then base64-encoded for Dominus wire protocol.
+5. HTTP request is sent.
+6. Response body is decoded from base64 and parsed.
+7. Errors are mapped to SDK error types.
+
+## 4. Routing Model
+
+- Namespace code generally targets `/api/*` endpoints.
+- For methods with `useGateway: true`, client route transform maps `/api/*` to gateway `/svc/*` dispatch paths.
+- Some methods intentionally use direct fetch paths (for example health checks/JWKS fetch).
+
+See [routes-services.md](./routes-services.md) for full route/service assessment.
+
+## 5. Auth and Token Handling
+
+### Service token flow
+
+- Input: `DOMINUS_TOKEN` (PSK)
+- Client exchanges PSK for short-lived JWT via gateway auth route.
+- JWT is cached with refresh buffer and refresh mutex to avoid thundering herd under concurrency.
+
+### User token flow
+
+- Methods that accept `userToken` pass caller JWT through unchanged.
+- Backend performs authorization checks for the user context.
+
+### Local JWT utilities
+
+- `verifyJwtLocally`, `isJwtValid`, and `mintSelectedScopeJwt` are exported from `src/lib/client.ts`. Selected-scope targeting is now the only supported SDK helper vocabulary.
+- `mintSelectedScopeJwt(targetOrgId, targetEnv)` is the canonical selected-scope mint helper; the live `/jwt/mint` contract keys selected scope off org plus environment, not a shared-routing flag.
+- `auth.getJwks` fetches public keys and caches them.
+- `auth.validateJwt` performs local payload checks/expiry validation.
+
+## 6. Caching and Resilience
+
+- Encrypted in-memory cache used for selected short-lived values (JWT, portal/session-related caches).
+- Circuit breaker support exists in transport/cache layer.
+- Retry with backoff is applied for transient request failures and mint flow.
+
+## 7. Streaming and Binary Paths
+
+- SSE: `streamRequest()` in client, used by AI streaming methods.
+- Multipart binary upload: `binaryUpload()`.
+- Binary download to `Buffer`: `binaryDownload()`.
+
+## 8. Speech APIs
+
+Speech routes are owned by agent-runtime through the `dominus.ai` namespace:
+
+- `dominus.ai.stt(audio, options?)` -> `POST /api/agent/stt`
+- `dominus.ai.tts(text, options?)` -> `POST /api/agent/tts`
+
+The legacy streaming STT namespace (`dominus.stt`) is retired in hard cutover.
+
+## 9. Documentation Topology
+
+Canonical documentation set for this repository:
+
+- [README.md](../README.md): overview and usage entry
+- [CLAUDE.md](../CLAUDE.md): agent conventions for this repo
+- [usage-reference.md](./usage-reference.md): exhaustive namespaced command reference
+- [routes-services.md](./routes-services.md): service and endpoint assessment
+
+## 10. Known Gaps
+
+- The hand-maintained command/namespace counts in `routes-services.md` and
+  `usage-reference.md` can drift from source; re-derive from `src/namespaces/*.ts`
+  and `src/index.ts` before quoting them.

package/docs/atlas/2026-07-24-1231-sdk-nodejs-blockers.md

@@ -1,15 +1,15 @@
-# Atlas Blockers: dominus-sdk-nodejs
-
-Generated: 2026-07-24 12:31 EDT
-
-## Blockers
-
-| ID | Blocker | Evidence | Likely owner | Workaround | Attack with |
-|---|---|---|---|---|---|
-| B1 | Docs/agent-guide may lag HEAD | Agent-guide snapshot(s) 2026-06-27-0849 — verify vs HEAD commits.; HEAD `8f41170` | `kyle-janitor` | Prefer code + CLAUDE | `kyle-janitor` |
-| B2 | Local tests not executed this pass | Docs-only atlas | CI | Run before behavior changes | Local/CI |
-
-## Recommended next skill
-
-1. `kyle-janitor` — refresh agent-guide if stale vs HEAD.
-2. Behavior defects → `kyle-diagnose` / owning expert skill.
+# Atlas Blockers: dominus-sdk-nodejs
+
+Generated: 2026-07-24 12:31 EDT
+
+## Blockers
+
+| ID | Blocker | Evidence | Likely owner | Workaround | Attack with |
+|---|---|---|---|---|---|
+| B1 | Docs/agent-guide may lag HEAD | Agent-guide snapshot(s) 2026-06-27-0849 — verify vs HEAD commits.; HEAD `8f41170` | `kyle-janitor` | Prefer code + CLAUDE | `kyle-janitor` |
+| B2 | Local tests not executed this pass | Docs-only atlas | CI | Run before behavior changes | Local/CI |
+
+## Recommended next skill
+
+1. `kyle-janitor` — refresh agent-guide if stale vs HEAD.
+2. Behavior defects → `kyle-diagnose` / owning expert skill.

package/docs/atlas/2026-07-24-1231-sdk-nodejs-proof-ladder.md

@@ -1,25 +1,25 @@
-# Atlas Proof Ladder: dominus-sdk-nodejs
-
-## Local Proof
-
-| Command | Expected signal | Status |
-|---|---|---|
-| `git status -sb` | Clean production branch @ `8f41170` | Observed via gather |
-| Test / typecheck | Pass | NOT RUN this pass |
-
-## CI / Release Proof
-
-| Surface | Expected signal | Status |
-|---|---|---|
-| Repo deploy workflows | Green on production branch pushes | Not re-run this pass |
-
-## Deploy / Live Proof
-
-| Surface | Expected signal | Status |
-|---|---|---|
-| Service health / package publish | Live or published artifact | Not probed this pass |
-
-## Positive vs No-Regression
-
-- **Positive:** Atlas pack exists at HEAD `8f41170` with dated proof pointers.
-- **No-regression:** Do not “fix” docs by reverting recent behavioral commits listed in the truthmap log.
+# Atlas Proof Ladder: dominus-sdk-nodejs
+
+## Local Proof
+
+| Command | Expected signal | Status |
+|---|---|---|
+| `git status -sb` | Clean production branch @ `8f41170` | Observed via gather |
+| Test / typecheck | Pass | NOT RUN this pass |
+
+## CI / Release Proof
+
+| Surface | Expected signal | Status |
+|---|---|---|
+| Repo deploy workflows | Green on production branch pushes | Not re-run this pass |
+
+## Deploy / Live Proof
+
+| Surface | Expected signal | Status |
+|---|---|---|
+| Service health / package publish | Live or published artifact | Not probed this pass |
+
+## Positive vs No-Regression
+
+- **Positive:** Atlas pack exists at HEAD `8f41170` with dated proof pointers.
+- **No-regression:** Do not “fix” docs by reverting recent behavioral commits listed in the truthmap log.