dominus-sdk-nodejs 6.6.0 → 7.1.0

package/docs/agent-guide/2026-06-27-0849-sdk-orient/02-repo-map-and-entrypoints.md

@@ -0,0 +1,46 @@
+# 02 Repo Map And Entrypoints
+
+## Directory Map
+
+| Path | Purpose |
+|---|---|
+| `src/index.ts` | Singleton construction, 27 namespace wiring, root shortcuts, public type/util re-exports. |
+| `src/lib/client.ts` | Transport: base64 wire protocol, JWT mint/cache, retries, circuit breaker, SSE, binary IO. |
+| `src/lib/cache.ts` | Encrypted in-memory cache + circuit breaker primitives. |
+| `src/lib/config.ts` | Env/config resolution (gateway/proxy). |
+| `src/lib/errors.ts` | Typed SDK error hierarchy. |
+| `src/lib/console-capture.ts` | Optional console forwarding to the logs namespace. |
+| `src/lib/page-rules.ts`, `src/lib/user-session.ts` | Portal JWT / page-access local caches. |
+| `src/lib/crypto.ts`, `schema-builder.ts`, `trace.ts`, `conversation-format.ts` | Helpers (crypto, schema-builder normalization, trace, conversation format). |
+| `src/namespaces/*.ts` | One file per namespace (27 files). |
+| `src/contracts/versioned-storage.ts` | Versioned-storage contract types. |
+| `tests/` | 24 test files (`.test.js`, `.test.ts`, `.typecheck.ts`). |
+| `docs/` | `architecture.md`, `routes-services.md`, `usage-reference.md`, `workflow-hard-cut-release.md`, plus this `agent-guide/` and `janitor/`. |
+| `.github/workflows/` | npm publish workflows by branch (dev/staging/production). |
+| `dist/` | Generated build output (gitignored). Not source. |
+| `node_modules/` | Installed deps (gitignored). |
+
+## Main Entrypoints
+
+- Public API: import `{ dominus }` from `dominus-sdk-nodejs` (resolves to
+  `dist/index.js`; source is `src/index.ts`).
+- Source-of-truth surface: `src/index.ts` constructor wires each
+  `public readonly <name>` namespace; a second wiring block builds a
+  token-scoped client subset.
+
+## Test Entrypoints
+
+- `npm test` builds, runs type tests, then runs the explicit node:test file list
+  in `package.json` `scripts.test`.
+- `npm run test:types` runs `tsc -p tsconfig.type-tests.json` for the
+  `*.typecheck.ts` files.
+
+## Config / Build / Deploy Entrypoints
+
+- `tsconfig.json` (build), `tsconfig.type-tests.json` (type tests).
+- `npm run build` (`tsc`) → `dist/`.
+- `.github/workflows/publish-production.yml` on push to `production`.
+
+## Avoid
+
+- `dist/` and `node_modules/` — generated; never edit, never cite as source.

package/docs/agent-guide/2026-06-27-0849-sdk-orient/03-api-surface.md

@@ -0,0 +1,59 @@
+# 03 API Surface
+
+The public surface is the `dominus` singleton (`src/index.ts`). Each namespace is
+a `public readonly` property backed by one file in `src/namespaces/`. The
+authoritative, exhaustive per-command reference is `docs/usage-reference.md`;
+the service/endpoint matrix is `docs/routes-services.md`. This page is the map.
+
+## Namespaces (27, wired in `src/index.ts`)
+
+| Namespace | File | Backend / role (see routes-services.md) |
+|---|---|---|
+| `dominus.secrets` | `secrets.ts` | warden (selected-scope grants). |
+| `dominus.db` | `db.ts` | db-worker. |
+| `dominus.secure` | `secure.ts` | scribe (audited secure-table access). |
+| `dominus.redis` | `redis.ts` | redis-worker (ephemera building block). |
+| `dominus.files` | `files.ts` | b2-worker / admin-worker. |
+| `dominus.auth` | `auth.ts` | guardian + local JWT helpers. |
+| `dominus.ddl` | `ddl.ts` | smith / db-worker (schema builder + provisioning). |
+| `dominus.logs` | `logs.ts` | logs-worker (tail supports `machine_id`). |
+| `dominus.portal` | `portal.ts` | portal-worker. |
+| `dominus.courier` | `courier.ts` | courier-worker. |
+| `dominus.health` | `health.ts` | gateway-local (`/health`, `/v1/ping`). |
+| `dominus.admin` | `admin.ts` | admin-worker. |
+| `dominus.ai` (+ `.rag`, `.tools`, `.workflow`, `.results`, `.artifacts`) | `ai.ts` | agent-runtime. |
+| `dominus.workflow` | `workflow.ts` | workflow-manager (`ensure()` is the public launch path). |
+| `dominus.sync` | `sync.ts` | sync-worker. |
+| `dominus.jobs` | `jobs.ts` | job-worker. |
+| `dominus.processor` | `processor.ts` | processor-service. |
+| `dominus.artifacts` | `artifacts.ts` | artifact-worker (Artifact V2 `ar://`). |
+| `dominus.authority` | `authority.ts` | authority (app/org/env cutover surface). |
+| `dominus.browser` | `browser.ts` | browser-worker via `/svc/browser/*`. |
+| `dominus.deployer` | `deployer.ts` | deploy surface. |
+| `dominus.warden` | `warden.ts` | warden. |
+| `dominus.stash` | `stash.ts` | **primary storage surface** (kind registry routes to backend). |
+| `dominus.recipes` | `recipes.ts` | recipe-worker. |
+| `dominus.platform` | `platform.ts` | platform-worker via `/svc/platform/*`. |
+| `dominus.coder` | `coder.ts` | coder-runtime via `/svc/coder/*`. |
+| `dominus.publisher` | `publisher.ts` | publisher. |
+
+(`ai` sub-namespaces and `auth` local helpers are extra surfaces beyond the 27
+top-level files; see routes-services.md for the full service matrix.)
+
+## Root Shortcuts And Utilities
+
+- Root shortcuts on the singleton: `get`, `upsert`, `listTables`, `queryTable`,
+  `insertRow`, `addTable`, etc. (`src/index.ts`).
+- Exported utilities/types: error classes, crypto helpers
+  (`hashPassword`, `hashPsk`, `generateToken`), cache utilities, JWT helpers
+  (`verifyJwtLocally`, `isJwtValid`, `mintSelectedScopeJwt`),
+  `normalizeSchemaBuilderMigration`, console-capture controls.
+
+## Auth / Scope Per Call
+
+- Default: service JWT minted from `DOMINUS_TOKEN` PSK via `/jwt/mint`, cached
+  55 min (`JWT_CACHE_TTL = 3300000`) vs the worker's 1h `JWT_EXPIRY_SECONDS`.
+- Optional `userToken` passes a caller JWT through unchanged where backend
+  semantics require user context.
+- `mintSelectedScopeJwt(targetOrgId, targetEnv)` is the canonical selected-scope
+  mint helper.

package/docs/agent-guide/2026-06-27-0849-sdk-orient/04-data-state-and-storage.md

@@ -0,0 +1,36 @@
+# 04 Data, State, And Storage
+
+This SDK is a stateless client; it does not own backend storage. It exposes
+storage-facing namespaces and keeps a few in-process caches. Backends own the
+durable state.
+
+## Storage Surfaces (client-facing)
+
+Per `docs/architecture.md` §2a (Two-Layer Storage Rule):
+
+| Surface | Namespace | Role |
+|---|---|---|
+| Named, durable data of a registered kind | `dominus.stash.*` | **Primary** — kind registry routes to the right backend + policy. |
+| Direct `ar://`-addressed Artifact V2 workflow | `dominus.artifacts.*` | Escape hatch when you already hold a canonical ref. |
+| Locks, queues, counters, short-lived cache | `dominus.redis.*` | Ephemera building block. |
+| Tables / SQL | `dominus.db.*`, `dominus.ddl.*` | db-worker / smith building blocks. |
+| Object/file storage | `dominus.files.*` | b2-worker building block. |
+| New kernel backend / documented fallback | primitives | Lowest layer only. |
+
+Rule: application data → Stash. Primitives only for ephemera or when building a
+kernel backend.
+
+## In-Process Client State (this repo)
+
+- **Service JWT cache** — `src/lib/client.ts`, cached 55 min, refreshed via
+  `ensureValidJwt` mutex to avoid thundering herd.
+- **Encrypted in-memory cache** — `src/lib/cache.ts`; encryption key seeded from
+  `DOMINUS_TOKEN` in `src/index.ts`.
+- **Portal/session caches** — `src/lib/page-rules.ts`, `src/lib/user-session.ts`
+  for portal JWT / page-access acceleration.
+- **JWKS cache** — `auth.getJwks` caches public signing keys.
+
+## Migrations
+
+- None in this repo. Schema/migration helpers (`ddl`, `normalizeSchemaBuilderMigration`)
+  build requests for the db/smith workers; the migrations themselves run there.

package/docs/agent-guide/2026-06-27-0849-sdk-orient/05-integrations-and-runtime.md

@@ -0,0 +1,40 @@
+# 05 Integrations And Runtime
+
+## External Dependencies
+
+- Runtime deps (`package.json`): `jose` (JWT verify/mint helpers), `bcryptjs`
+  (password/PSK hashing).
+- Dev deps: `typescript`, `@types/node`, `@types/bcryptjs`.
+
+## Cross-Repo / Gateway Calls
+
+The SDK is a client to the Dominus gateway. Namespace code targets `/api/*`
+paths; when a method sets `useGateway: true` the client transforms `/api/*` to
+gateway `/svc/*` dispatch paths (`docs/architecture.md` §4,
+`docs/routes-services.md`). Backends reached include guardian, authority,
+workflow-manager, agent-runtime, db/redis/b2/logs workers, platform-worker,
+coder-runtime, browser-worker, and others — see the service matrix in
+`docs/routes-services.md`.
+
+Notable routing facts (from `CLAUDE.md` / routes-services.md):
+
+- `dominus.browser.*` must use `/api/browser/*` with `useGateway: true`
+  (gateway exposes `/svc/browser/*`); do not point at worker-local `/runs/*`.
+- `dominus.platform.*` and `dominus.coder.*` call `/svc/*` via `gatewayFetch`
+  and forward `X-Actor-Type` / `X-Actor-Id`.
+- `dominus.coder.ensureRun()` requires exactly one of `workflowRecipeRef` or
+  `pipelineRecipeRef`.
+- `dominus.ai.stt` → `POST /api/agent/stt` (batch; legacy WebSocket STT retired).
+
+## Runtime Assumptions
+
+- ESM only (`"type": "module"`), Node `>=18`.
+- Single published entry point; import from `'dominus-sdk-nodejs'` only.
+
+## Environment Variables (by category, no values)
+
+- **Auth:** `DOMINUS_TOKEN` (PSK; also seeds the in-memory cache encryption key).
+- **Gateway/config:** resolved in `src/lib/config.ts` (gateway base URL / proxy
+  config). Read that file for the exact variable names before relying on one.
+
+Never write secret values into docs or logs.

package/docs/agent-guide/2026-06-27-0849-sdk-orient/06-workflows-commands-and-ci.md

@@ -0,0 +1,58 @@
+# 06 Workflows, Commands, And CI
+
+All commands from `package.json` `scripts`.
+
+## Install
+
+```bash
+npm ci        # CI / reproducible
+npm install   # local
+```
+
+## Build / Dev
+
+```bash
+npm run build   # tsc -> dist/
+npm run dev     # tsc --watch
+npm run clean   # rm -rf dist
+```
+
+## Typecheck / Lint
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm run lint        # tsc --noEmit (lint == typecheck in this repo)
+npm run test:types  # tsc -p tsconfig.type-tests.json (the *.typecheck.ts files)
+```
+
+## Test
+
+```bash
+npm test
+```
+
+`npm test` = `build` + `test:types` + an explicit `node --test` file list (24
+files under `tests/`). Run before finalizing substantial changes (`CLAUDE.md`
+Validation). Tests are committed and present — the older "no committed tests"
+note is stale.
+
+## Fast Local Validation
+
+`npm run typecheck` (or `lint`) for a quick compile check; `npm run test:types`
+for the type-level contract tests.
+
+## Full Validation
+
+`npm test` (build + type tests + unit/contract tests).
+
+## CI Workflows
+
+| Workflow | Trigger | Signal |
+|---|---|---|
+| `.github/workflows/publish-production.yml` | push to `production` | `npm ci` + build + npm publish (skips if version already on registry; falls back to provenance publish). |
+| `.github/workflows/publish-staging.yml` | (staging branch) | npm publish lane. |
+| `.github/workflows/publish-development.yml` | (development branch) | npm publish lane. |
+
+Per workspace reality, only the `production` lane is the live publish path for
+this repo. Publishing is version-gated: bump `package.json` `version` or the
+publish step no-ops.

package/docs/agent-guide/2026-06-27-0849-sdk-orient/07-operations-release-and-live-proof.md

@@ -0,0 +1,40 @@
+# 07 Operations, Release, And Live Proof
+
+## Deployment Lane
+
+This is a published npm package, not a deployed service. "Release" = npm publish.
+
+- Push to `production` → `.github/workflows/publish-production.yml` →
+  `npm publish --access public`.
+- Per workspace convention this repo's production branch is `production` (NOT
+  `dominus-production`, which is the convention for other Dominus repos).
+- Requires GitHub Environment `production` with `NPM_TOKEN` (or npm OIDC trusted
+  publishing for the provenance-only retry).
+
+## Release Files And Version Rules
+
+- `package.json` `version` is the single source of truth (6.6.0 at this
+  snapshot). The publish step checks `npm view <name>@<version>` and skips if the
+  version already exists, so **a version bump is required to publish**.
+- `CHANGELOG.md` records each version's changes; update it with the bump.
+- `package.json` `files` ships `dist`, `README.md`, and `docs`.
+- `prepublishOnly` runs `npm run build` so `dist/` is fresh in the tarball.
+
+## Live Proof
+
+- Registry: `npm view dominus-sdk-nodejs version` should match the pushed
+  `package.json` version after the workflow succeeds.
+- CI: the publish-production workflow run on the `production` push.
+
+## Done Definitions
+
+- **Local done:** `npm test` green (build + type tests + unit/contract tests).
+- **CI done:** publish-production workflow succeeds.
+- **Release done:** new version visible on npm.
+
+## Rollback
+
+Per `docs/workflow-hard-cut-release.md`: downgrade target is the previously
+published production SDK version. Trigger: customers report Authority-backed
+recipe launch or native pipelines cannot start. (npm versions are immutable;
+"rollback" means consumers pin the prior version.)

package/docs/agent-guide/2026-06-27-0849-sdk-orient/08-security-privacy-and-secrets.md

@@ -0,0 +1,38 @@
+# 08 Security, Privacy, And Secrets
+
+## Auth Boundaries
+
+- **Service auth:** `DOMINUS_TOKEN` PSK → minted short-lived JWT via gateway
+  `/jwt/mint`, cached (`src/lib/client.ts`). Default for namespace calls.
+- **User auth:** optional `userToken` passes a caller JWT through unchanged;
+  the backend authorizes the user context.
+- **Selected-scope:** `mintSelectedScopeJwt(targetOrgId, targetEnv)` is the only
+  supported selected-scope mint helper; scope keys off org + environment.
+- **Local JWT helpers:** `verifyJwtLocally`, `isJwtValid`, `auth.validateJwt`
+  (local payload/expiry checks — not full remote introspection), `auth.getJwks`
+  (cached public keys).
+
+Identity-family rule (workspace policy): service token, service JWT, portal user
+JWT, client JWT, and selected-scope operator token are NOT interchangeable. Do
+not forward a user or machine JWT to admin-only planes.
+
+Service-side 401 rule (`CLAUDE.md`): a non-`/portal/auth/*` 401 must not be
+laundered into user-session expiry by callers. Classify by
+`DominusError.endpoint`, not message strings — every `getServiceJwt` throw
+carries `endpoint='/jwt/mint'`.
+
+## Secret / Config Resolution
+
+- `src/lib/config.ts` resolves gateway/proxy/url config and `DOMINUS_TOKEN`
+  from env. No secret values are committed.
+- `.gitignore` excludes `.env`, `.env.local`, `.env.*.local`, `.npmrc`.
+
+## PHI / Sensitive-Data Rules
+
+- This SDK carries no PHI itself, but it transports caller data to backends.
+- Never log or write into docs: PHI, secret values, tokens, cookies, JWTs, raw
+  request/response bodies.
+
+## Must Never Be Written Into Docs
+
+Tokens, PSKs, JWTs, secret values, raw response bodies, customer/patient data.

package/docs/agent-guide/2026-06-27-0849-sdk-orient/09-known-risks-and-debt.md

@@ -0,0 +1,34 @@
+# 09 Known Risks And Debt
+
+## Stale Docs (corrected this pass)
+
+- `docs/architecture.md` §10 and `CLAUDE.md` Validation note claimed "no
+  committed automated tests". STALE — `tests/` has 24 committed files run by
+  `npm test`. Corrected in both files in this janitor pass. If a future edit
+  re-introduces the claim, fix it; do not trust it.
+
+## Doc Maintenance Burden
+
+- `docs/usage-reference.md` is ~98 KB and `docs/routes-services.md` cites
+  "450 commands across 29 namespace surfaces". These hand-maintained counts can
+  drift from source. Treat `src/namespaces/*.ts` + `src/index.ts` as authority;
+  re-derive counts before quoting them. (At this snapshot: 27 namespace files,
+  24 test files.)
+
+## Generated Residue
+
+- `dist/` (~1.6 MB) is built output, gitignored; safe to delete and rebuild with
+  `npm run build`. Auto-cleaned this pass (see janitor audit). `node_modules/`
+  likewise reproducible via `npm ci`.
+
+## Ownership / Boundaries
+
+- The SDK must conform to kernel contracts (identity families, error envelope,
+  routing) defined in the Dominus workers — it does not define them. Changes that
+  touch wire protocol, JWT TTLs, or route transforms are contract-sensitive and
+  warrant `dominus-expert` review before shipping.
+
+## Cleanup Links
+
+- Janitor audit: `docs/janitor/2026-06-27-0849-sdk-orient-cleanup-audit.md`.
+- No `docs/atlas/` exists; run `kyle-atlas` if truth becomes scattered.

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

@@ -0,0 +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.

package/docs/agent-guide/INDEX.md

@@ -0,0 +1,23 @@
+# Agent Guide Index
+
+Last updated: 2026-06-27 08:49 local
+Current snapshot: `2026-06-27-0849-sdk-orient/00-reading-order.md`
+
+## Use This When
+
+You are a coding agent about to change `dominus-sdk-nodejs` and want to orient
+from docs before reading source: what this repo is, how a request flows, where
+to edit a namespace, how to prove a change, and which facts are stale.
+
+## Read Order
+
+1. `2026-06-27-0849-sdk-orient/00-reading-order.md`
+2. `2026-06-27-0849-sdk-orient/01-purpose-and-boundaries.md`
+3. `2026-06-27-0849-sdk-orient/03-api-surface.md`
+4. `2026-06-27-0849-sdk-orient/10-agent-playbook.md`
+
+## Snapshot History
+
+| Snapshot | Reason | Notes |
+|---|---|---|
+| `2026-06-27-0849-sdk-orient` | First janitor agent-guide pack | Source-backed at SDK v6.6.0 on branch `production`. |

package/docs/agent-guide/current.md

@@ -0,0 +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.

package/docs/architecture.md

@@ -114,4 +114,6 @@ Canonical documentation set for this repository:
 
 ## 10. Known Gaps
 
-- Test script exists in `package.json`, but no committed automated tests are currently present in this repository.
+- 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/janitor/2026-06-27-0849-sdk-orient-cleanup-audit.md

@@ -0,0 +1,102 @@
+# Janitor Cleanup Audit: dominus-sdk-nodejs
+
+Generated: 2026-06-27 08:49 local
+Target repo: C:\developer\codingroot\repos\dominus_active\dominus-sdk-nodejs
+Git root: C:\developer\codingroot\repos\dominus_active\dominus-sdk-nodejs
+Branch/status: `production` — clean before this pass (no tracked or untracked changes).
+
+## Summary
+
+Wrote a source-backed agent-guide pack and wired it into `README.md` and
+`CLAUDE.md`. Corrected one proven-stale fact ("no committed automated tests")
+in three places. Auto-cleaned generated `dist/` (gitignored, reproducible).
+Everything left uncommitted per instructions. No tracked source, branches,
+worktrees, plans, or release artifacts deleted.
+
+## Executive Actions Applied
+
+| Action | Path | Why safe | Verification |
+|---|---|---|---|
+| Wrote agent-guide pack | `docs/agent-guide/**` | New docs only; no source touched. | Files present; INDEX/current point at snapshot. |
+| Wrote cleanup audit | `docs/janitor/2026-06-27-0849-sdk-orient-cleanup-audit.md` | New doc only. | This file. |
+| Wired guide into README | `README.md` | Added small "Agent Guide" section near top; no other content changed. | `git diff README.md` is the one added block. |
+| Wired guide into CLAUDE | `CLAUDE.md` | Added "Agent Guide Pack" pointer near top. | `git diff CLAUDE.md`. |
+| Fixed stale tests fact | `CLAUDE.md`, `docs/architecture.md` | `tests/` has 24 committed files run by `npm test`; old "no committed tests" claim was provably false. | `ls tests` (24 files); `package.json scripts.test` lists them. |
+| Auto-clean generated build | `dist/` | Gitignored, untracked, reproducible via `npm run build`; `prepublishOnly` rebuilds it. | `git check-ignore dist` = ignored; `git ls-files dist` empty; post-delete `git status` shows no tracked change. |
+
+## Docs Written
+
+| File | Purpose | Source-backed by |
+|---|---|---|
+| `docs/agent-guide/INDEX.md` | Stable entrypoint + snapshot history. | repo layout. |
+| `docs/agent-guide/current.md` | Latest snapshot pointer + top-5 refresh facts. | `package.json`, `src/index.ts`, `tests/`. |
+| `.../00-reading-order.md` | Read order + per-task source map + stale flags. | existing docs, `src/`. |
+| `.../01-purpose-and-boundaries.md` | Purpose, ownership, runtime class, boundary. | `package.json`, `CLAUDE.md`, workflows. |
+| `.../02-repo-map-and-entrypoints.md` | Directory map + entrypoints. | `find src`, `package.json`, `.github/workflows`. |
+| `.../03-api-surface.md` | 27 namespaces + auth/scope map. | `src/index.ts` wiring, `routes-services.md`. |
+| `.../04-data-state-and-storage.md` | Storage surfaces + in-process caches. | `docs/architecture.md` §2a, `src/lib/*`. |
+| `.../05-integrations-and-runtime.md` | Deps, gateway routing, env categories. | `package.json`, `CLAUDE.md`, `src/lib/config.ts`. |
+| `.../06-workflows-commands-and-ci.md` | Commands + CI lanes. | `package.json scripts`, `.github/workflows`. |
+| `.../07-operations-release-and-live-proof.md` | npm release lane + proof. | `publish-production.yml`, `package.json`, `workflow-hard-cut-release.md`. |
+| `.../08-security-privacy-and-secrets.md` | Auth boundaries, secret resolution. | `CLAUDE.md`, `src/lib/config.ts`, `.gitignore`. |
+| `.../09-known-risks-and-debt.md` | Stale docs, doc-drift, generated residue. | this audit, `docs/*`. |
+| `.../10-agent-playbook.md` | If-changing-X-read-Y + Kyle routing. | `CLAUDE.md`, `src/`. |
+
+## Drift Findings
+
+| Finding | Evidence | Risk | Recommendation | Approval needed |
+|---|---|---|---|---|
+| "No committed automated tests" claim stale | `tests/` has 24 files; `package.json scripts.test` runs them | Low (misleads agents) | Fixed in CLAUDE.md + architecture.md §10 | Done |
+| Hand-maintained counts may drift | `routes-services.md` says "450 commands / 29 surfaces"; actual `src/namespaces/` = 27 files | Low | Noted in 09 + architecture §10; re-derive from source before quoting | No |
+
+## Stale Or Conflicting Docs
+
+| Doc | Problem | Stronger source | Proposed action |
+|---|---|---|---|
+| `docs/architecture.md` §10 | claimed no committed tests | `tests/` + `package.json` | Fixed (replaced with count-drift note). |
+| `CLAUDE.md` Validation | "If tests are absent" framing | `tests/` (24 files) | Fixed to state tests are committed. |
+| `routes-services.md` counts | "29 namespace surfaces" vs 27 top-level files | `src/namespaces/` | Left as-is (counts include `ai.*` sub-namespaces + `auth` local helpers; not provably wrong). Flagged for re-derivation. |
+
+## Orphan / Generated / Scratch Candidates
+
+| Path | Evidence | Proposed action | Safe now? |
+|---|---|---|---|
+| `dist/` | gitignored build output (~1.6 MB) | Deleted | Yes (done) |
+| `node_modules/` | gitignored installed deps | Leave; not in the auto-apply allowlist; reproducible via `npm ci` but may be in use by a dev session | Not auto-deleted |
+
+## Auto-Cleanup Performed
+
+| Path | Evidence | Action | Verification |
+|---|---|---|---|
+| `dist/` | `git check-ignore dist` = ignored; `git ls-files dist` empty; reproducible via `npm run build` | `rm -rf dist` | Post-delete `git status` shows no tracked change; rebuild with `npm run build`. |
+
+## Expert Review Queue
+
+| Candidate | Why expert should view it first | Suggested expert | First review question |
+|---|---|---|---|
+| `routes-services.md` "450 commands / 29 surfaces" reconciliation | Authoritative re-count of public commands vs. the maintained matrix touches the platform client contract surface | dominus-expert | Are the documented counts accurate against current `src/namespaces/*.ts`, and should they be regenerated by a script instead of hand-maintained? |
+
+## Worktree / Branch / Plan Residue
+
+| Item | Evidence | Proposed action | Owner |
+|---|---|---|---|
+| None | Single repo dir; no `.git/worktrees` scratch, no stray plans found | None | — |
+
+## Approval Queue
+
+- [ ] Delete `node_modules/` (reproducible via `npm ci`) — only if no dev session is using it — validate with `npm ci && npm test`.
+
+## Not Touching
+
+- `dist/` rebuild — left for the developer to regenerate via `npm run build`.
+- `node_modules/` — installed deps; outside the granted auto-clean allowlist.
+- `docs/usage-reference.md` (~98 KB) — large reference, not rewritten; only flagged for count drift.
+- All tracked source, `CHANGELOG.md` history, CI workflows, branches.
+
+## Follow-Up Skills
+
+| Need | Skill | First action |
+|---|---|---|
+| Reconcile documented command counts | dominus-expert | Re-count public commands against `src/namespaces/`. |
+| If truth scatters across code/docs/CI | kyle-atlas | Build `docs/atlas/INDEX.md`. |
+| Durable cross-repo facts | kyle-learn | Promote to `.claude/knowledge` if reused. |

package/docs/routes-services.md

@@ -2,7 +2,7 @@
 
 This assessment is derived from all public namespace methods under `src/namespaces/` and their configured routes in SDK request calls.
 
-Audited commands: **450** across **29** namespace surfaces.
+Audited commands: **~450** (hand-counted) across **27** top-level namespace files in `src/namespaces/`. The Service Matrix below lists **29** namespace surfaces because it expands dotted sub-namespaces (e.g. `ai.*` and `auth.*`) into their own rows, so the surface count is intentionally higher than the file count, not a typo. These totals are hand-maintained — re-derive from source before quoting.
 
 ## Service Matrix
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dominus-sdk-nodejs",
-  "version": "6.6.0",
+  "version": "7.1.0",
   "description": "Node.js SDK for the Dominus gateway-first platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,7 +21,7 @@
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit",
-    "test": "npm run build && npm run test:types && node --test tests/auth.test.js tests/health.test.js tests/browser.test.js tests/recipes.test.js tests/recipes-stash-routing.test.js tests/platform-coder.test.js tests/publisher.test.js tests/workflow-lifecycle.test.js tests/logs.test.js tests/public-exports.test.js tests/authority-contract.test.js tests/error-contract.test.js tests/admin.test.js tests/control-plane.test.js tests/schema-builder-contract.test.js tests/files-contract.test.js tests/storage-wire-contract.test.js tests/stash-artifact-facade.test.js tests/conversation-format.test.js",
+    "test": "npm run build && npm run test:types && node --test tests/auth.test.js tests/health.test.js tests/browser.test.js tests/recipes.test.js tests/recipes-stash-routing.test.js tests/platform-coder.test.js tests/publisher.test.js tests/workflow-lifecycle.test.js tests/logs.test.js tests/public-exports.test.js tests/authority-contract.test.js tests/error-contract.test.js tests/admin.test.js tests/control-plane.test.js tests/schema-builder-contract.test.js tests/files-contract.test.js tests/storage-wire-contract.test.js tests/stash-artifact-facade.test.js tests/conversation-format.test.js tests/per-call-controls.test.js",
     "test:types": "tsc -p tsconfig.type-tests.json",
     "lint": "tsc --noEmit"
   },