nats - SKILL.md Agent Skill

name: nats description: Use when publishing or subscribing to NATS from the Self Serve Express BFF — touching `nats.service.ts`, sending NATS requests, consuming subjects, or troubleshooting NATS connectivity. Trigger phrases include "NATS publish", "NATS subscribe", "NATS request", "nats.service", "project RPC", "inter-service messaging". allowed-tools: Bash, Read, Write, Edit, Glob, Grep

You are publishing, subscribing, or making NATS request/reply calls from the Self Serve Express BFF.

A backend endpoint needs to look up a resource via NATS request/reply (e.g., project RPC for ID resolution).
A backend service consumes a NATS subject (e.g., listening for indexer or persona updates).
A new server-side code path needs to publish to NATS.
Investigating "no responder" / timeout / connection errors in nats.service.ts.

Re-read docs/architecture/backend/nats-integration.md (the reference linked below). It documents the singleton connection, request/reply timeout defaults, project resolution, and the subject conventions Self Serve consumes.
Do not bypass nats.service.ts — it is a protected file. Use the existing helper methods; add new methods through code-owner review.
Use the right subject vocabulary — subjects are owned by their producing service (per /lfx-skills:lfx). Do not invent new subjects from Self Serve; coordinate with the owning service repo first.
Set explicit timeouts on request/reply calls. Failures must surface as MicroserviceError (or equivalent) and route through next(error) — never res.status(500).json().
Log via the logger service (not serverLogger). Use logger.debug for subject + reply tracing, logger.error for failed requests.
Mock mode — for local dev without the full platform stack, follow docs/architecture/backend/nats-integration.md and the mock-mode setup in /setup. Do not introduce ad-hoc mocks inside production code paths.

docs/architecture/backend/nats-integration.md — the canonical NATS architecture doc. Treat this as the source of truth; do not maintain a separate copy under this skill.

This skill does NOT cover the platform NATS deployment (routes to lfx-v2-helm).
It does NOT cover indexer or FGA-sync subject contracts (routes to lfx-v2-indexer-service and lfx-v2-fga-sync via /lfx-skills:lfx).
It does NOT cover the upstream auth or persona NATS contracts (route to lfx-v2-auth-service / lfx-v2-persona-service).