docs: add pkg/tsnats NATS client to Go MCP design

MCP remains the AI tool surface. Importable pkg/tsnats covers Stamp,
Verify, HashReport over core NATS plus SubscribeCompleted; MCP optional
upstream reuses the same package. No JetStream for job-complete.

README.md

@@ -6,6 +6,8 @@ Go MCP timestamping server for Verae. Digests only; sibling to the Python server
 
 Implements the same tools as https://mcp.verae.ai/mcp (`stamp`, `verify`, `hash_report`, auth tools) using the official MCP Go SDK. Designed for shadow deploy beside Python, then cutover.
 
+AI assistants use MCP. Bulk app workers can import `pkg/tsnats` for core NATS request/reply on `verae.ts.*` (job-complete stays ephemeral; no JetStream for those events).
+
 ## Table of Contents
 
 - [Install](#install)

docs/superpowers/specs/2026-09-29-go-mcp-timestamping-server-design.md

@@ -17,6 +17,7 @@ The live Verae MCP timestamping service is a Python process (`verae-mcp-timestam
 4. Optional core-NATS bridge (same subjects as Python); **no JetStream for job-complete**.
 5. Streamable HTTP + stdio transports; CORS / allowed hosts/origins compatible with ns1.
 6. Shadow on ns1 beside Python; documented cutover checklist.
+7. Importable **`pkg/tsnats`** NATS client for bulk app workers (MCP stays the AI path).
 
 ## Non-goals (this project)
 
@@ -35,16 +36,21 @@ The live Verae MCP timestamping service is a Python process (`verae-mcp-timestam
 ## Architecture
 
 ```
-Clients
-   │
-   ▼
-verae-mcp-timestamping-server-go
-   ├── local|shared → FileLedger (~/.verae/mcp-timestamp-local.json or VERAE_LEDGER_PATH)
-   ├── global       → api.veraetime.net (/api/timestamp, /api/verify, /api/hash/{sha}, /auth/*)
-   └── optional NATS → verae.ts.request, verae.ts.verify, verae.hash.report (core NATS only)
+AI assistants ──MCP (stdio / Streamable HTTP)──► verae-mcp-timestamping-server-go
+                                                    ├── FileLedger (local|shared)
+                                                    ├── VeraeTime HTTPS (global)
+                                                    └── optional upstream NATS (same pkg/tsnats)
+
+Bulk apps / bus workers ──pkg/tsnats──► NATS core
+                         request/reply: verae.ts.request | verae.ts.verify | verae.hash.report
+                         notify (subscribe): verae.ts.completed / receipt-style subjects
+                         (no JetStream for job-complete)
 ```
 
+**Split:** MCP tools remain the AI surface. `pkg/tsnats` is the digests-only messaging client for large concurrent stamp batches and async completion.
+
 **SDK:** official `github.com/modelcontextprotocol/go-sdk/mcp` (`NewStreamableHTTPHandler`, `AddTool`, stdio).  
+**NATS:** `github.com/nats-io/nats.go` inside `pkg/tsnats` (and reused by `internal/natsbridge`).
 
 ## Repository layout
 
@@ -53,11 +59,12 @@ Remote (planned): `ssh://git@git.georgelambert.org:2223/marchon/verae-mcp-timest
 
 ```
 cmd/verae-mcp-timestamping-server/main.go
+pkg/tsnats/               # importable NATS timestamp client (Stamp/Verify/HashReport + Completed)
 internal/config/
 internal/digest/
 internal/ledger/          # FileLedger
 internal/veraetime/       # GlobalClient + auth.properties
-internal/natsbridge/      # optional
+internal/natsbridge/      # optional MCP upstream; wraps pkg/tsnats
 internal/tools/           # MCP tool handlers
 docs/superpowers/specs/
 docs/cutover.md           # cutover checklist (deliverable)
@@ -85,6 +92,24 @@ Digests only: reject content/bytes/file/data/path/body/payload/blob/archive.
 Normalize SHA-256 (optional `sha256:` prefix; 64 hex).  
 Global stamp: `restamp: false`; poll `/api/status/{jobId}` when needed.
 
+## pkg/tsnats (bulk app client)
+
+Import path (planned): `git.georgelambert.org/marchon/verae-mcp-timestamping-server-go/pkg/tsnats`
+
+| API | Behavior |
+| --- | --- |
+| `Connect(url string, opts ...Option) (*Client, error)` | Core NATS connection |
+| `Stamp(ctx, sha256, opts)` | Request/reply on `verae.ts.request`; digests only |
+| `Verify(ctx, receiptID, opts)` | `verae.ts.verify` |
+| `HashReport(ctx, sha256, opts)` | `verae.hash.report` |
+| `SubscribeCompleted(ctx, handler)` | Core subscribe to `verae.ts.completed` (and documented receipt alias if any); **not** JetStream |
+
+Defaults: request timeout ~2s (configurable); concurrent `Stamp` calls are safe; empty/invalid digests fail client-side before publish.
+
+The MCP server’s optional NATS upstream (`internal/natsbridge`) **imports this package** so bus encoding stays one implementation.
+
+Bulk guidance: prefer many in-flight `Stamp` calls (or fire request + `SubscribeCompleted`) over serial MCP `tools/call`. For central global certificates when not on the bus, Application Client / VeraeTime HTTPS remains valid.
+
 ## Config (env)
 
 | Variable | Default |
@@ -132,6 +157,7 @@ Global stamp: `restamp: false`; poll `/api/status/{jobId}` when needed.
 - Full tool list matches Python.
 - Local/shared persist to ledger file; global uses VeraeTime with caller/host token.
 - Optional NATS path does not use JetStream for job-complete.
+- `pkg/tsnats` builds as an importable library with unit tests against a NATS test server or fake conn.
 - Shadow unit runs on ns1 without disturbing Python `:8000`.
 - Cutover doc is complete enough to swap without inventing steps on the day.