@warlock.js/herald 5.34.1 → 5.34.3

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@warlock.js/herald` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.34.3 - 2026-10-20
+
+### Changed
+
+- Condensed the package agent skill description to at most 450 characters, with API names and package routing guidance.
+
+## 5.34.2 - 2026-10-19
+
+### Fixed
+
+- Remove the redundant loose skill catalog and include package orientation in generated LLM projections.
+
 ## 5.33.0 - 2026-10-19
 
 ### Changed

package/llms-full.txt

@@ -4,7 +4,34 @@
 
 > Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/herald/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
 
-## consume-message  `@warlock.js/herald/consume-message/SKILL.md`
+## Package orientation
+
+---
+description: 'Broker messaging over RabbitMQ: `connectToBroker`, `herald`, `heraldChannel`, `defineEvent`, `defineConsumer`, `EventMessage` and `EventConsumer`. Use for "publish an event", "subscribe to a channel", "ack or nack", "request and reply" or cross-service pub/sub. Not this package → @warlock.js/queue for durable retried background jobs; @warlock.js/scheduler for cron; @warlock.js/notifications for user notifications.'
+---
+
+# @warlock.js/herald
+
+Herald is the broker-agnostic message bus. `connectToBroker(config)` boots a broker once; `herald()` returns it (`herald("name")` for a named one); `.channel(name)` is the queue/topic you publish into and subscribe from. Channels are typed with generics and can validate with a seal schema. Server-only.
+
+## The 80% path
+
+1. Orient with `herald-basics.md` (the map and foundations).
+2. Connect at startup, then publish: `publish-message.md`.
+3. Consume with `subscribe` handlers or consumer classes: `consume-message.md`.
+4. Need a reply? `request-and-respond.md`.
+
+## Conventions and pitfalls
+
+- Call `connectToBroker` once before any publish or subscribe.
+- Smart auto-ack is the default: a clean return acks, a throw nacks with requeue. `autoAck: true` loses messages on a crash; avoid it.
+- Use `ctx.reject()` / `ctx.retry(ms)` only for a non-default outcome.
+- Herald is transport, not a job runner: no retries-as-jobs, no scheduling. Use `@warlock.js/queue` for retried jobs, `@warlock.js/scheduler` for cron.
+- Install the driver (`amqplib`) yourself; Kafka is not shipped yet.
+- Do not value-import from client code.
+
+
+## consume-message  `@warlock.js/herald/skills/consume-message/SKILL.md`
 
 ---
 name: consume-message
@@ -229,7 +256,7 @@ await channel.delete(); // remove the queue entirely
 - The `request-and-respond` topic — when you need to reply to a message
 
 
-## herald-basics  `@warlock.js/herald/herald-basics/SKILL.md`
+## herald-basics  `@warlock.js/herald/skills/herald-basics/SKILL.md`
 
 ---
 name: herald-basics
@@ -334,7 +361,7 @@ herald("analytics").channel("events").publish({/* ... */}); // → analytics
 - The `seal-basics` topic of the `warlock-js-seal` skill — schema validation
 
 
-## publish-message  `@warlock.js/herald/publish-message/SKILL.md`
+## publish-message  `@warlock.js/herald/skills/publish-message/SKILL.md`
 
 ---
 name: publish-message
@@ -513,7 +540,7 @@ Set an optional `version` on the event (instance field) to drive the consumer's
 - The `request-and-respond` topic — when you need a reply
 
 
-## request-and-respond  `@warlock.js/herald/request-and-respond/SKILL.md`
+## request-and-respond  `@warlock.js/herald/skills/request-and-respond/SKILL.md`
 
 ---
 name: request-and-respond

package/llms.txt

@@ -6,7 +6,8 @@
 
 ## Skills
 
-- [consume-message](@warlock.js/herald/consume-message/SKILL.md): Subscribe to a channel via .subscribe(handler, options?) — handler receives (message, ctx). Control flow via ctx.ack / ctx.nack(requeue?) / ctx.reject / ctx.retry(delayMs). Configure prefetch, retry policy, dead-letter, consumer groups. Triggers: `subscribe`, `ctx.ack`, `ctx.nack`, `ctx.reject`, `ctx.retry`, `prefetch`, `group`, `retry`, `deadLetter`, `@Consumable`, `EventConsumer`, `defineConsumer`, `autoAck`; "consume messages from a queue", "implement a worker", "background queue processor", "set up retry and dead-letter", "class-based event consumer"; typical import `import { herald, Consumable, EventConsumer } from "@warlock.js/herald"`. Skip: setup — the `herald-basics` topic; producing — the `publish-message` topic; RPC reply — the `request-and-respond` topic; competing libs `amqplib`, `bullmq`, `kafkajs`; NestJS `@MessagePattern` / `@EventPattern`.
-- [herald-basics](@warlock.js/herald/herald-basics/SKILL.md): Start here for @warlock.js/herald event publishing, consumers, request-response messaging, and configuration.
-- [publish-message](@warlock.js/herald/publish-message/SKILL.md): Publish messages to a channel — .publish(payload, options?) for single, .publishBatch([...], options?) for batch, with priority / ttl / delay / persistent / correlationId / headers options. Optional schema validation via .channel(name, {schema}). Triggers: `publish`, `publishBatch`, `channel`, `priority`, `ttl`, `delay`, `persistent`, `correlationId`, `headers`, `schema`; "publish a message", "emit an event after a domain change", "fan out a notification", "schedule delayed work", "batch publish"; typical import `import { herald } from "@warlock.js/herald"`. Skip: setup — the `herald-basics` topic; consuming — the `consume-message` topic; RPC — the `request-and-respond` topic; competing libs `amqplib`, `kafkajs`, `bullmq`; NestJS `ClientProxy.emit`.
-- [request-and-respond](@warlock.js/herald/request-and-respond/SKILL.md): Synchronous-style RPC over the message bus — channel.request<R>(payload, {timeout}) waits for a reply, channel.respond(handler) registers the responder, ctx.reply(response) sends the answer. Triggers: `channel.request`, `channel.respond`, `ctx.reply`, `timeout`, `correlationId`, `headers.correlationId`; "RPC over message bus", "request-response across services", "wait for a reply", "internal service-to-service call instead of HTTP"; typical import `import { herald } from "@warlock.js/herald"`. Skip: setup — the `herald-basics` topic; fire-and-forget — the `publish-message` topic; consumer ctx flow — the `consume-message` topic; competing libs `amqplib` RPC, `nats` request/reply; NestJS `ClientProxy.send`; gRPC; HTTP.
+- [Package orientation](@warlock.js/herald/skills/index.md): Broker messaging over RabbitMQ: `connectToBroker`, `herald`, `heraldChannel`, `defineEvent`, `defineConsumer`, `EventMessage` and `EventConsumer`. Use for "publish an event", "subscribe to a channel", "ack or nack", "request and reply" or cross-service pub/sub. Not this package → @warlock.js/queue for durable retried background jobs; @warlock.js/scheduler for cron; @warlock.js/notifications for user notifications.
+- [consume-message](@warlock.js/herald/skills/consume-message/SKILL.md): Subscribe to a channel via .subscribe(handler, options?) — handler receives (message, ctx). Control flow via ctx.ack / ctx.nack(requeue?) / ctx.reject / ctx.retry(delayMs). Configure prefetch, retry policy, dead-letter, consumer groups. Triggers: `subscribe`, `ctx.ack`, `ctx.nack`, `ctx.reject`, `ctx.retry`, `prefetch`, `group`, `retry`, `deadLetter`, `@Consumable`, `EventConsumer`, `defineConsumer`, `autoAck`; "consume messages from a queue", "implement a worker", "background queue processor", "set up retry and dead-letter", "class-based event consumer"; typical import `import { herald, Consumable, EventConsumer } from "@warlock.js/herald"`. Skip: setup — the `herald-basics` topic; producing — the `publish-message` topic; RPC reply — the `request-and-respond` topic; competing libs `amqplib`, `bullmq`, `kafkajs`; NestJS `@MessagePattern` / `@EventPattern`.
+- [herald-basics](@warlock.js/herald/skills/herald-basics/SKILL.md): Start here for @warlock.js/herald event publishing, consumers, request-response messaging, and configuration.
+- [publish-message](@warlock.js/herald/skills/publish-message/SKILL.md): Publish messages to a channel — .publish(payload, options?) for single, .publishBatch([...], options?) for batch, with priority / ttl / delay / persistent / correlationId / headers options. Optional schema validation via .channel(name, {schema}). Triggers: `publish`, `publishBatch`, `channel`, `priority`, `ttl`, `delay`, `persistent`, `correlationId`, `headers`, `schema`; "publish a message", "emit an event after a domain change", "fan out a notification", "schedule delayed work", "batch publish"; typical import `import { herald } from "@warlock.js/herald"`. Skip: setup — the `herald-basics` topic; consuming — the `consume-message` topic; RPC — the `request-and-respond` topic; competing libs `amqplib`, `kafkajs`, `bullmq`; NestJS `ClientProxy.emit`.
+- [request-and-respond](@warlock.js/herald/skills/request-and-respond/SKILL.md): Synchronous-style RPC over the message bus — channel.request<R>(payload, {timeout}) waits for a reply, channel.respond(handler) registers the responder, ctx.reply(response) sends the answer. Triggers: `channel.request`, `channel.respond`, `ctx.reply`, `timeout`, `correlationId`, `headers.correlationId`; "RPC over message bus", "request-response across services", "wait for a reply", "internal service-to-service call instead of HTTP"; typical import `import { herald } from "@warlock.js/herald"`. Skip: setup — the `herald-basics` topic; fire-and-forget — the `publish-message` topic; consumer ctx flow — the `consume-message` topic; competing libs `amqplib` RPC, `nats` request/reply; NestJS `ClientProxy.send`; gRPC; HTTP.

package/package.json

@@ -8,8 +8,8 @@
     "@mongez/copper": "^2.1.3",
     "@mongez/events": "^2.2.8",
     "@mongez/reinforcements": "^4.0.2",
-    "@warlock.js/logger": "5.34.1",
-    "@warlock.js/seal": "5.34.1"
+    "@warlock.js/logger": "5.34.3",
+    "@warlock.js/seal": "5.34.3"
   },
   "repository": {
     "type": "git",
@@ -37,7 +37,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.34.1",
+  "version": "5.34.3",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/index.md

@@ -1,5 +1,5 @@
 ---
-description: 'Message bus over RabbitMQ (Kafka planned): publish, subscribe, and request-response between services. Exports `connectToBroker`, `herald`, `heraldChannel`, `Broker`, `defineEvent`, `defineConsumer`, `EventMessage`, `EventConsumer`, `Consumable`, `brokerRegistry`. Use for: "publish an event to RabbitMQ", "subscribe to a channel", "ack or nack a message", "request and reply over the bus", "cross-service messaging". Not this package: durable retried background jobs on Redis → @warlock.js/queue; cron/recurring work → @warlock.js/scheduler.'
+description: 'Broker messaging over RabbitMQ: `connectToBroker`, `herald`, `heraldChannel`, `defineEvent`, `defineConsumer`, `EventMessage` and `EventConsumer`. Use for "publish an event", "subscribe to a channel", "ack or nack", "request and reply" or cross-service pub/sub. Not this package → @warlock.js/queue for durable retried background jobs; @warlock.js/scheduler for cron; @warlock.js/notifications for user notifications.'
 ---
 
 # @warlock.js/herald

package/skills/README.md

@@ -1,21 +0,0 @@
-# `@warlock.js/herald` — skills index
-
-Per-task skills. All cross-references use the form `@warlock.js/<pkg>/<skill>/SKILL.md`.
-
-## Skills
-
-### `consume-message`
-
-Subscribe to a channel via .subscribe(handler, options?) — handler receives (message, ctx). Control flow via ctx.ack / ctx.nack(requeue?) / ctx.reject / ctx.retry(delayMs). Configure prefetch, retry policy, dead-letter, consumer groups. Load when implementing a worker processing events, a queue background processor, or consuming an event log.
-
-### `herald-basics`
-
-Start with @warlock.js/herald — connectToBroker config, herald() factory, channel concept, multi-broker support. Load when wiring connectToBroker at boot, choosing a herald skill, or wiring multiple brokers (notifications + analytics + events).
-
-### `publish-message`
-
-Publish messages to a channel — .publish(payload, options?) for single, .publishBatch([...], options?) for batch, with priority / ttl / delay / persistent / correlationId / headers options. Optional schema validation via .channel(name, {schema}). Load when emitting an event after a domain change, fanning out a notification, or scheduling delayed work.
-
-### `request-and-respond`
-
-Synchronous-style RPC over the message bus — channel.request<R>(payload, {timeout}) waits for a reply, channel.respond(handler) registers the responder, ctx.reply(response) sends the answer. Load when needing a request-response shape across services with loose coupling instead of direct HTTP.