@cowliss/cli 0.13.0 → 0.14.0

package/blueprints/abandoned-checkout/events.json

@@ -0,0 +1,9 @@
+{
+  "checkout_started": {
+    "cartId": "cart_10482",
+    "checkoutUrl": "https://store.example.com/checkout/10482"
+  },
+  "purchase_completed": {
+    "orderId": "ord_10482"
+  }
+}

package/blueprints/activity-decay/events.json

@@ -0,0 +1 @@
+{}

package/blueprints/ecommerce/events.json

@@ -0,0 +1,28 @@
+{
+  "checkout.started": {
+    "cartId": "cart_10482",
+    "checkoutUrl": "https://store.example.com/checkout/10482",
+    "total": 110.0
+  },
+  "order.delivered": {
+    "orderId": "ord_10482"
+  },
+  "order.placed": {
+    "orderId": "ord_10482",
+    "total": 110.0,
+    "items": [
+      {
+        "name": "Linen shirt",
+        "price": 78.0
+      },
+      {
+        "name": "Canvas tote",
+        "price": 32.0
+      }
+    ]
+  },
+  "product.viewed": {
+    "productId": "prod_linen_shirt",
+    "category": "apparel"
+  }
+}

package/blueprints/mobile-game/events.json

@@ -0,0 +1,22 @@
+{
+  "level.completed": {
+    "level": 4,
+    "score": 1250
+  },
+  "level.failed": {
+    "level": 4,
+    "attempts": 3
+  },
+  "purchase.completed": {
+    "packId": "starter_bundle",
+    "coins": 500,
+    "price": 4.99
+  },
+  "session.started": {
+    "platform": "ios",
+    "version": "1.2.0"
+  },
+  "tutorial.completed": {
+    "step": "boss_fight"
+  }
+}

package/blueprints/saas-trial/events.json

@@ -0,0 +1,18 @@
+{
+  "invite.sent": {
+    "recipientEmail": "colleague@example.com",
+    "role": "editor"
+  },
+  "project.created": {
+    "projectId": "proj_123",
+    "template": "starter"
+  },
+  "subscription.created": {
+    "plan": "pro",
+    "seats": 5
+  },
+  "trial.started": {
+    "plan": "trial",
+    "days": 14
+  }
+}

package/blueprints/winback/events.json

@@ -0,0 +1,6 @@
+{
+  "purchase_completed": {
+    "orderId": "ord_10482",
+    "amount": 49.99
+  }
+}

package/dist/index.js

@@ -23,6 +23,40 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 
+//#endregion
+//#region ../../packages/shared/src/agent-prompts/index.ts
+function buildEventsPrompt(args) {
+	if (!args.sdkPackage?.trim()) throw new Error("sdkPackage is required");
+	if (!args.trackMethod?.trim()) throw new Error("trackMethod is required");
+	if (!args.referenceUrl?.trim()) throw new Error("referenceUrl is required");
+	if (!Array.isArray(args.events) || args.events.length === 0) throw new Error("events list must not be empty");
+	const lines = [
+		`Send these events from your application using ${args.sdkPackage}:`,
+		"",
+		`Reference documentation: ${args.referenceUrl}`,
+		""
+	];
+	for (const event of args.events) {
+		if (!event.name?.trim()) throw new Error("event name is required");
+		lines.push(`### Event: \`${event.name}\``);
+		if (event.description) lines.push(`${event.description}`);
+		lines.push("");
+		if (event.payload) {
+			lines.push("Example payload:");
+			lines.push("```json");
+			lines.push(JSON.stringify(event.payload, null, 2));
+			lines.push("```");
+			lines.push("");
+		}
+		lines.push("Code example:");
+		lines.push("```ts");
+		lines.push(`await ${args.trackMethod}({`, "  identifiers: { /* the same identifiers you pass to identify */ },", `  event: ${JSON.stringify(event.name)},`, `  properties: ${JSON.stringify(event.payload ?? {})},`, "});");
+		lines.push("```");
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+
 //#endregion
 //#region ../../packages/shared/src/constants.ts
 /** The public docs site, for the mail and the pages that point people at it. */
@@ -99,6 +133,12 @@ const IDENTIFIER_KINDS = [
 	"email"
 ];
 /**
+* The monthly free allowance, in micro-dollars. Every org gets it, no plan
+* required: it resets at each UTC calendar month and does not roll over.
+* Spend past it draws the prepaid wallet balance.
+*/
+const FREE_ALLOWANCE_MICROS = 4e6;
+/**
 * The fixed-amount one-time top-ups, in micro-dollars ($10 / $50 / $200,
 * provisional). A topup is a single Stripe Checkout payment; the wallet
 * credit carries over month to month. Provisional numbers live here so a
@@ -109,6 +149,8 @@ const TOPUP_PRESETS_MICROS = [
 	5e7,
 	2e8
 ];
+/** Micro-dollars in one dollar; the only place a display conversion starts. */
+const MICRO_DOLLARS_PER_DOLLAR = 1e6;
 /**
 * The marketing purpose by name, since it is the one every gate, the
 * unsubscribe route, and the developer's own toggle all reach for.
@@ -5687,6 +5729,10 @@ const walletTopupSchema = z.object({
 	completedAt: z.iso.datetime().nullable()
 });
 const listWalletTopupsQuerySchema = paginationQuerySchema;
+/** Micro-dollars as a plain dollar string, for the whole-dollar constants. */
+function dollars(micros) {
+	return `$${micros / MICRO_DOLLARS_PER_DOLLAR}`;
+}
 
 //#endregion
 //#region ../../packages/shared/src/governance.ts
@@ -7673,7 +7719,10 @@ const templateSchema = z.object({
 * manifest entry, and searching inside that is a query the database layer
 * would have to grow a helper for. The badges in each row still show them.
 */
-const listTemplatesQuerySchema = paginationQuerySchema.extend({ q: z.string().trim().max(200, "q must be at most 200 characters").optional().transform((value) => value ? value : void 0) });
+const listTemplatesQuerySchema = paginationQuerySchema.extend({
+	appId: appIdSchema.optional(),
+	q: z.string().trim().max(200, "q must be at most 200 characters").optional().transform((value) => value ? value : void 0)
+});
 /** The props a preview or a test send renders the template with. */
 const renderTemplateBodySchema = z.object({ data: z.object({ props: z.record(z.string(), z.unknown()).default({}) }) });
 /** A test send is a delivery like any other, so it takes the same props. */
@@ -9604,8 +9653,11 @@ const createRoute = (routeConfig) => {
 //#region ../../packages/shared/src/contract/define.ts
 /**
 * `createRoute` with the contract's additions: a required `operationId`
-* (`<tag>.<verb>`, kept as a literal type so handler maps can key on it) and
-* the `surfaces` block.
+* (`<tag>.<verb>`, kept as a literal type so handler maps can key on it),
+* `tags` drawn from `TAG_DOCS`, and the `surfaces` block. An optional
+* `description` is the text the summary cannot carry: it renders under the
+* operation in the docs, after the summary in the MCP tool, and after the
+* options in `cow <command> --help`.
 */
 function defineRoute(config) {
 	return createRoute(config);
@@ -9746,6 +9798,7 @@ const apps = defineModule(defineRoute({
 	operationId: "apps.update",
 	tags: ["apps"],
 	summary: "Rename or archive an app",
+	description: "Admin only. Archiving is permanent: an archived app cannot be unarchived or modified. Renaming changes the display name only; the app id never changes.",
 	security: SESSION_AUTH,
 	request: {
 		params: params$11,
@@ -9779,9 +9832,7 @@ const apps = defineModule(defineRoute({
 //#region ../../packages/shared/src/contract/artifacts.ts
 /**
 * Raw artifact transfer, the one place in the API where bytes travel outside
-* an envelope. `cow push` HEADs every digest it built and PUTs only the ones
-* the org does not already have, so a rebuild that changes one journey
-* uploads one bundle.
+* an envelope (the story is the `artifacts` intro in `tags.ts`).
 *
 * Both routes are hidden from the CLI and MCP surfaces: they are plumbing
 * for the composite `cow push`, not something a human or an agent invokes
@@ -9857,6 +9908,7 @@ const billing = defineModule(defineRoute({
 	operationId: "billing.topups.create",
 	tags: ["billing"],
 	summary: "Start a wallet top-up",
+	description: "Admin only. Returns a hosted checkout URL to redirect to. `amountMicros` must be one of the fixed presets.",
 	security: SESSION_AUTH,
 	request: { body: jsonBody(createTopupBodySchema) },
 	responses: {
@@ -9947,6 +9999,7 @@ const catalog = defineModule(defineRoute({
 	operationId: "catalog.events.setState",
 	tags: ["catalog"],
 	summary: "Allow or deny an event name",
+	description: "Denying an event name permanently drops any entries held for it in the review queue.",
 	security: SESSION_AUTH,
 	request: {
 		params: params$10,
@@ -10003,6 +10056,7 @@ const catalog = defineModule(defineRoute({
 	operationId: "catalog.traits.update",
 	tags: ["catalog"],
 	summary: "Update a catalog trait",
+	description: "A trait type is frozen when registered and cannot be changed. Requests that specify a different `type` are rejected.",
 	security: SESSION_AUTH,
 	request: {
 		params: params$10,
@@ -10020,6 +10074,7 @@ const catalog = defineModule(defineRoute({
 	operationId: "catalog.traits.setState",
 	tags: ["catalog"],
 	summary: "Allow or deny a trait name",
+	description: "Denying a trait name permanently drops any entries held for it in the review queue.",
 	security: SESSION_AUTH,
 	request: {
 		params: params$10,
@@ -10036,6 +10091,7 @@ const catalog = defineModule(defineRoute({
 	operationId: "catalog.quarantine.promote",
 	tags: ["catalog"],
 	summary: "Promote a quarantined name into the catalog",
+	description: "Allow-lists the name in the catalog and backfills all held entries. Held events are recorded with their original timestamps, and held trait values apply to profiles in occurrence order.",
 	security: SESSION_AUTH,
 	request: { body: jsonBody(quarantineActionBodySchema) },
 	responses: {
@@ -10050,6 +10106,7 @@ const catalog = defineModule(defineRoute({
 	operationId: "catalog.quarantine.deny",
 	tags: ["catalog"],
 	summary: "Deny a quarantined name",
+	description: "Denies the name in the catalog and permanently drops all entries held for it in the review queue.",
 	security: SESSION_AUTH,
 	request: { body: jsonBody(quarantineActionBodySchema) },
 	responses: {
@@ -10128,6 +10185,7 @@ const deliveries = defineModule(defineRoute({
 	operationId: "deliveries.sesFeedback",
 	tags: ["deliveries"],
 	summary: "SES delivery feedback via SNS (public)",
+	description: "Updates delivery statuses, adds bounced and complained addresses to your suppression list, and revokes consent on complaints. Open tracking events are rejected because open tracking is disabled. Subscription confirmation requests from the platform's email provider are confirmed automatically.",
 	security: NO_AUTH,
 	surfaces: HIDDEN_FROM_TOOLS,
 	request: { body: { content: { "text/plain": { schema: z.string() } } } },
@@ -10141,6 +10199,7 @@ const deliveries = defineModule(defineRoute({
 	operationId: "deliveries.unsubscribe",
 	tags: ["deliveries"],
 	summary: "One-click unsubscribe (public)",
+	description: "Revokes consent for the purpose the email was sent under on the recipient's profile. Setting `all` to `1` revokes the master `marketing` purpose instead, stopping all marketing email.",
 	security: NO_AUTH,
 	surfaces: HIDDEN_FROM_TOOLS,
 	request: { query: tokenQuery.extend({ 
@@ -10248,6 +10307,7 @@ const domains = defineModule(defineRoute({
 	operationId: "domains.update",
 	tags: ["domains"],
 	summary: "Toggle click tracking",
+	description: "Enabling click tracking requires a verified domain, while disabling is always allowed. Tracking covers every email sent from the domain, including transactional email.",
 	security: SESSION_AUTH,
 	request: {
 		params: params$9,
@@ -10264,6 +10324,7 @@ const domains = defineModule(defineRoute({
 	operationId: "domains.delete",
 	tags: ["domains"],
 	summary: "Give up a sending domain",
+	description: "Sending from this domain stops immediately, and the domain becomes available for any organization to claim.",
 	security: SESSION_AUTH,
 	request: { params: params$9 },
 	responses: {
@@ -10318,6 +10379,7 @@ const emails = defineModule(defineRoute({
 	operationId: "emails.verify",
 	tags: ["emails"],
 	summary: "Verify an email address (public)",
+	description: "Marks the address verified. If the profile associated with the link still carries that address, sets `emailVerified` to `true` and records a `system.email_verified` event.",
 	security: NO_AUTH,
 	surfaces: HIDDEN_FROM_TOOLS,
 	request: { query: tokenQuery },
@@ -10375,6 +10437,7 @@ const events = defineModule(defineRoute({
 	operationId: "apps.events.seen",
 	tags: ["events"],
 	summary: "Whether an app has ever received these event names",
+	description: "A name may be a pattern where `*` matches any run of characters against the whole name. A pattern reports the latest timestamp among matching events, or `null` if the app has never received one.",
 	security: PIPELINE_AUTH,
 	surfaces: { cli: false },
 	request: {
@@ -10436,6 +10499,7 @@ const executions = defineModule(defineRoute({
 	operationId: "executions.cancel",
 	tags: ["executions"],
 	summary: "Cancel live executions of a journey, or of one version",
+	description: "Admin only. Each execution stops when it reaches its next step.",
 	security: SESSION_AUTH,
 	request: { body: jsonBody(cancelExecutionsBodySchema) },
 	responses: {
@@ -10546,6 +10610,7 @@ const ingestion = defineModule(defineRoute({
 	operationId: "ingestion.batch",
 	tags: ["ingestion"],
 	summary: "Import one source's calls in one request",
+	description: "Batch writes skip triggers on raw events, but segments still recompute and a journey triggered by segment entry can fire. A failing item is reported in the response and does not fail the rest of the batch.",
 	security: API_KEY_AUTH,
 	surfaces: HIDDEN_FROM_TOOLS,
 	request: { body: jsonBody(batchBodySchema) },
@@ -10626,6 +10691,7 @@ const journeys = defineModule(defineRoute({
 	operationId: "journeys.setStatus",
 	tags: ["journeys"],
 	summary: "Put journeys on, off or on hold",
+	description: "Admin only. Turning a journey off lets executions in flight finish, while putting it on hold pauses them before their next step. Turning a held journey on resumes them.",
 	security: PIPELINE_AUTH,
 	surfaces: { cli: false },
 	request: { body: jsonBody(setJourneysStatusBodySchema) },
@@ -10656,6 +10722,7 @@ const journeys = defineModule(defineRoute({
 	operationId: "journeys.delete",
 	tags: ["journeys"],
 	summary: "Delete a journey",
+	description: "Admin only. Executions already in flight finish, but no new ones start. A push never deletes a journey, so this is the only way to remove one whose file was deleted from your code.",
 	security: SESSION_AUTH,
 	request: { params: params$7 },
 	responses: {
@@ -10682,6 +10749,7 @@ const journeys = defineModule(defineRoute({
 	operationId: "journeys.startEnrollment",
 	tags: ["journeys"],
 	summary: "Enroll the journey's current members",
+	description: "Admin only. Starts an enrollment for recipients currently in the journey's segment. If an enrollment is already running, this returns the existing enrollment rather than starting another.",
 	security: SESSION_AUTH,
 	surfaces: HIDDEN_FROM_TOOLS,
 	request: { params: params$7 },
@@ -10709,6 +10777,7 @@ const journeys = defineModule(defineRoute({
 	operationId: "journeys.cancelEnrollment",
 	tags: ["journeys"],
 	summary: "Stop a running enrollment",
+	description: "Admin only. Recipients already enrolled remain in the journey and their executions continue. Stopping the enrollment only prevents remaining recipients from enrolling.",
 	security: SESSION_AUTH,
 	request: { params: params$7 },
 	responses: {
@@ -10722,6 +10791,7 @@ const journeys = defineModule(defineRoute({
 	operationId: "journeys.dryRun",
 	tags: ["journeys"],
 	summary: "Dry-run a journey against a real user",
+	description: "Admin only. Runs the journey's latest ready version against the specified profile with sends disabled, delivering no emails or webhooks. The execution proceeds even if the journey is turned off.",
 	security: SESSION_AUTH,
 	request: {
 		params: params$7,
@@ -10816,6 +10886,7 @@ const pushes = defineModule(defineRoute({
 	operationId: "pushes.create",
 	tags: ["pushes"],
 	summary: "Push a built app",
+	description: "Every bundle and the source archive must be uploaded before creating the push. The push is refused if any referenced artifact is missing, or if a journey's `from` address uses a domain your organization has not verified.",
 	security: PIPELINE_AUTH,
 	surfaces: HIDDEN_FROM_TOOLS,
 	request: { body: jsonBody(createPushBodySchema) },
@@ -11056,6 +11127,7 @@ const segments = defineModule(defineRoute({
 	operationId: "segments.update",
 	tags: ["segments"],
 	summary: "Update a segment",
+	description: "Updating a segment's `definition` recomputes its membership over existing profile history. A segment defined in code (in a journey trigger or your project's `segments/` directory) cannot be updated here: change the code and push the project again.",
 	security: SESSION_AUTH,
 	request: {
 		params: params$5,
@@ -11073,6 +11145,7 @@ const segments = defineModule(defineRoute({
 	operationId: "segments.delete",
 	tags: ["segments"],
 	summary: "Delete a segment",
+	description: "Deleting a segment permanently removes all of its members. A segment defined in code (in a journey trigger or your project's `segments/` directory) cannot be deleted here: remove it from your project and push again.",
 	security: SESSION_AUTH,
 	request: { params: params$5 },
 	responses: {
@@ -11117,6 +11190,7 @@ const settings = defineModule(defineRoute({
 	operationId: "settings.update",
 	tags: ["settings"],
 	summary: "Update org settings",
+	description: "Admin only. Lowering `eventRetentionDays` permanently deletes stored events older than the new window.",
 	security: SESSION_AUTH,
 	request: { body: jsonBody(updateOrgSettingsBodySchema) },
 	responses: {
@@ -11182,6 +11256,7 @@ const settings = defineModule(defineRoute({
 	operationId: "settings.pipelineKeys.revoke",
 	tags: ["settings"],
 	summary: "Revoke an org pipeline key",
+	description: "Revocation is permanent. Calls authenticating with this key can still be accepted for up to a minute.",
 	security: SESSION_AUTH,
 	request: {
 		params: z.object({ id: z.string() }),
@@ -11198,6 +11273,7 @@ const settings = defineModule(defineRoute({
 	operationId: "settings.apiKeys.revoke",
 	tags: ["settings"],
 	summary: "Revoke an org API key",
+	description: "Revocation is permanent. Calls authenticating with this key stop being accepted immediately.",
 	security: SESSION_AUTH,
 	request: {
 		params: z.object({ id: z.string() }),
@@ -11215,10 +11291,9 @@ const settings = defineModule(defineRoute({
 const appParams = z.object({ appId: z.string() });
 const params$4 = z.object({ id: z.string() });
 /**
-* A source is one inbound pipe into an app. It is created and listed under
-* its parent app (the app is the attribution unit) and addressed by its own
-* id afterwards. The webhook receiver is public: the provider's signature is
-* its authorization.
+* Sources: created and listed under their parent app (so those two routes
+* carry the `apps` tag), addressed by their own id afterwards. The customer
+* story is the `sources` intro in `tags.ts`.
 */
 const sources = defineModule(defineRoute({
 	method: "post",
@@ -11287,6 +11362,7 @@ const sources = defineModule(defineRoute({
 	operationId: "sources.archive",
 	tags: ["sources"],
 	summary: "Archive a source",
+	description: "Admin only. Archiving is irreversible and immediately stops this source from accepting calls or webhook deliveries. For an `api` source, this halts ingestion for the parent app until you add a replacement.",
 	security: SESSION_AUTH,
 	request: { params: params$4 },
 	responses: {
@@ -11335,6 +11411,7 @@ const suppressions = defineModule(defineRoute({
 	operationId: "suppressions.delete",
 	tags: ["suppressions"],
 	summary: "Un-suppress an address",
+	description: "Admin only. Clears the address at the email provider so future sends can be attempted. If the provider cannot be reached, the address remains suppressed.",
 	security: SESSION_AUTH,
 	request: { params: z.object({ id: z.string() }) },
 	responses: {
@@ -11345,19 +11422,160 @@ const suppressions = defineModule(defineRoute({
 }));
 
 //#endregion
-//#region ../../packages/shared/src/contract/templates.ts
+//#region ../../packages/shared/src/contract/tags.ts
 /**
-* Templates: the emails a journey sends, addressed by key like a journey.
-* A template has versions and nothing else (ADR 0011), so there is no
-* create and no update here: templates arrive with a push, and the only
-* writes are rendering one to look at it, sending one to yourself, and
-* deleting the key.
+* The prose for every contract tag: the API reference page's title,
+* description and intro, the OpenAPI document's `tags[]`, and the CLI's help
+* line for a command group named after a tag. Route `tags` are typed against
+* this record, so a new tag without an entry fails typecheck.
 *
-* `preview` and `testSend` both render the latest version that finished
-* compiling, in the sandbox, with the props the caller passes. `testSend`
-* then sends that message to the caller's own address through the
-* organization's default sender: it reaches no recipient, so it passes no
-* consent gate, counts against nothing, and is logged as a test.
+* Intro links are docs-site-relative (`/tracking/apps/`): the docs render
+* them as written, and `buildOpenApiDocument` prefixes them with DOCS_URL.
+*/
+const TAG_DOCS = {
+	health: {
+		title: "Health",
+		description: "Liveness and readiness probes.",
+		intro: "These routes are orchestration probes. Both sit outside the `/v1` prefix and need no credential."
+	},
+	ingestion: {
+		title: "Ingestion",
+		description: "POST /v1/identify, /v1/track, and /v1/batch: the org API-key-authenticated write path.",
+		intro: "The write path ingests traits and events using an organization API key (`Authorization: Bearer <key>`). All calls sit behind the organization rate limiter and the billing hard stop, and dedupe retries using `Idempotency-Key` or `messageId`. Every call requires the `sourceId` of an `api` source, from which Cowliss derives and stamps the app (see [Apps tracking](/tracking/apps/)). Calls with an unknown, archived, or non-API `sourceId` are rejected. Event names starting with `system.` are rejected because that prefix is reserved for events Cowliss writes itself (see [Event patterns](/journeys/#the-system-namespace))."
+	},
+	users: {
+		title: "Users",
+		description: "Profiles: list, search, the 360 view, consent editing, merged event history, segment membership, GDPR export and erasure.",
+		intro: "A profile holds what an app knows about a recipient: traits, identifiers, the consent map, merged event history, and segment membership. When a profile is merged into another, requests to its `usr_` id redirect to the survivor's URL. GDPR export and erasure can target a single profile by its `usr_` id, taking everything merged into it, or every profile across your apps that carries an identifier. All routes require session-token authentication, and erasure requires `org:admin`."
+	},
+	consent: {
+		title: "Consent purposes",
+		description: "The consent purposes your organization's profiles answer: `marketing` plus the ones your own code declares.",
+		intro: "Every profile's `consent` map answers these purposes, and every switch that offers one is labelled from here. One is fixed for every organization, `marketing`, the master switch every other purpose sits under; the rest are whatever your code declares under `purposes` in [`cow.json`](/guides/repo/). `transactional` is not here: it is why a receipt or an alert goes out, which is not something a recipient chooses, so nothing stores an answer to it. Purposes are code, like journeys and templates, so this resource is read-only: a push is what adds or relabels one, and nothing ever deletes one, because profiles already hold answers against it."
+	},
+	events: {
+		title: "Events",
+		description: "The org-wide event feed, per-app volume stats, and single-event fetch.",
+		intro: "These routes provide read views over your event history. Events are append-only and never rewritten. Ingestion writes are on the [Ingestion](/reference/api/ingestion/) page."
+	},
+	apps: {
+		title: "Apps",
+		description: "The app registry: your apps and products, and the sources that push into them.",
+		intro: "An app is the attribution unit for one product: it carries no kind, configuration, or credential of its own, and each event and profile carries its `appId`. Inbound pipes into an app are sources created under it, and all of an app's sources land on the same profiles. This includes the first-party `api` source created with the app, which the SDK and HTTP path write through. Routes that address a source by its own id (including the public webhook receiver) are on the [Sources](/reference/api/sources/) page. See the [Apps and sources guide](/tracking/apps/)."
+	},
+	sources: {
+		title: "Sources",
+		description: "Sources addressed by id: config rotation, archiving, and the public webhook receiver.",
+		intro: "A source is one inbound pipe into an [app](/reference/api/apps/): each app is created with the first-party `api` source, and a `kind` is singleton per app. Sources are created and listed under their parent app, and these routes address one by its own `id`. All writes are attributed to the source's parent app. The signing secret in `config` is write-only and never present in any response: `configured` reports whether one is stored. The webhook receiver is public: the caller's signature is the authorization, and the route answers with plain text rather than the envelope. See the [Apps and sources guide](/tracking/apps/)."
+	},
+	catalog: {
+		title: "Catalog",
+		description: "The tracking plan: event and trait definitions, governance states (allow/deny), and the strict-mode quarantine review queue.",
+		intro: "The catalog is the tracking plan: event and trait definitions addressed by name, unique per organization, each in a governance state (`allowed`, `denied`, or `quarantined`, where denied always wins). Ingestion accepts by default, rejecting only denied names and canonical traits that fail format validation. With the org's `ingestionPolicy` set to `strict`, unclassified names are held in the quarantine review queue instead of applied. Property and trait types: " + propertyTypeSchema.options.map((type) => `\`${type}\``).join(", ") + ". Observation infers an array's item type when its members agree, and `array<any>` when they do not or the array is empty."
+	},
+	review: {
+		title: "Review queue",
+		description: "One list over both halves of the review queue: names held unapplied under a strict policy, and names accepted but flagged under a permissive one.",
+		intro: "The review queue brings together everything ingestion parked for a person to decide on, replacing the two lists it unions. A held name is a write a strict policy would not apply until its name is classified; a violation is a name a permissive policy accepted and flagged. Both carry a `kind` and `name` alongside a first and a last sighting, so they list together under one cursor, ordered by last seen. This resource is a read and nothing else, as the per-item verbs stay where they are: allow or deny a held name on the [Catalog](/reference/api/catalog/) page, and resolve or dismiss a violation on the [Violations](/reference/api/violations/) page."
+	},
+	violations: {
+		title: "Violations",
+		description: "Tracking-plan violations: unknown names accepted but flagged, with one-click resolve into the catalog or dismissal.",
+		intro: "In permissive mode, an unknown event or trait name is accepted and flagged here, so a typo never silently drops data. Resolving a violation registers the name into [the catalog](/reference/api/catalog/) pre-filled from the observed payload, while dismissing silences noise. Resolving and dismissing are admin only."
+	},
+	segments: {
+		title: "Segments",
+		description: "Computed audiences: predicate definitions, preview, member lists, and the recomputation lifecycle.",
+		intro: "Segments are predicate definitions over traits and event history, recomputed synchronously on each write. Transitions emit `system.segment_entered` and `system.segment_exited` system events that journeys trigger on, except those found by a bulk recompute, which start nobody. See the [Segments guide](/segments/) for predicate semantics. All mutations require organization admin permissions."
+	},
+	journeys: {
+		title: "Journeys",
+		description: "One journey per key: trigger, tags, recorded step spine, the enable switch, and operational stats.",
+		intro: "A journey is addressed by the key its author gave the file, running its latest ready version. Status decides whether the journey fires, and a push never touches it: a key is off until it is turned on. The `spine` is read from the journey's source and is display only: what a journey does during execution is whatever its code decides. A journey belongs to one app and fires on that app's events only. A trigger's `event` is a pattern in which `*` matches any sequence of characters, one or a list of them, and a pattern reaches Cowliss's own `system.` events only when its literal prefix starts with `system.`: see [Event patterns](/journeys/#event-patterns). Executions are on the [Executions](/reference/api/executions/) page."
+	},
+	templates: {
+		title: "Templates",
+		description: "The email templates a journey sends: their props, who sends them, rendering one, and sending yourself a test.",
+		intro: "Templates are the email templates a journey sends, each addressed by the key its author gave the file. Templates arrive with a push, so there is no create and no update here. A template has versions and nothing else, no switch, because a send resolves the latest version that finished compiling at the moment it sends, so fixing copy reaches executions already in flight."
+	},
+	artifacts: {
+		title: "Artifacts",
+		description: "Content-addressed bundle and source storage: HEAD to check, PUT to upload.",
+		intro: "Artifacts are immutable bytes named by their own `sha256:` digest and deduplicated within an organization. They serve as plumbing for `cow push` so changing one journey transfers only one bundle, and remain documented for anyone reimplementing push. This is the one place in the API where bytes travel outside an envelope. The body of a `PUT` must hash to the digest it is filed under, and repeat transfers of the same digest are a no-op. These routes carry their own size limit rather than the global request one."
+	},
+	pushes: {
+		title: "Pushes",
+		description: "One push per cow push: the whole project at one point in time, and the versions it compiles.",
+		intro: "A push stores the app's source archive and creates a new version of every journey and template whose bundle changed; a key that did not change gets none. The push returns as soon as it is stored, and each version compiles on its own, so one file that cannot compile costs its own key and nothing else. A push turns nothing on: journey `status` is untouched."
+	},
+	versions: {
+		title: "Versions",
+		description: "One key's history: every version of a journey or a template, newest first.",
+		intro: "A version is an immutable, content-addressed snapshot of one journey or one template. It is read-only and addressed through its key rather than on its own path. Journeys and templates share a key space, so both `key` and `kind` are required. The latest `ready` version is the code new executions and new sends use, which leaves the previous version running when a compile fails."
+	},
+	executions: {
+		title: "Executions",
+		description: "One run of one journey for one profile, pinned to the version it started on.",
+		intro: "An execution is one journey for one profile, pinned to the version it started on. It can be filtered by journey, version, status, and profile in one place. Its detail carries what the journey logged with `api.log`. Pipeline keys can read executions, but stopping them is explicit: `cancel` is the only write and requires a dashboard session."
+	},
+	webhooks: {
+		title: "Webhooks",
+		description: "The URLs a journey POSTs a Standard-Webhooks-signed payload to, one registry the journey references by name.",
+		intro: "Journeys reference webhooks by name, so journey code never hardcodes a URL. A webhook carries its own signing secret, shown only at creation. Payloads follow the Standard Webhooks convention with the `v: 1` version field and `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. A webhook with too many consecutive failures auto-disables until re-enabled. All mutations require `org:admin`."
+	},
+	domains: {
+		title: "Sending domains",
+		description: "Org-verified sending domains: claims, the DNS records to install, verification status, and manual re-check.",
+		intro: "An organization cannot send without a verified domain. Claims are global and exact-string: a parent or child of a claimed domain conflicts. The `dnsRecords` array specifies what your DNS must carry (three DKIM CNAMEs, the MX return path and its SPF TXT, plus a recommended DMARC TXT), each with its own status. DNS is re-checked on a schedule and nothing pushes an event when it is, so status refreshes are pull-only."
+	},
+	deliveries: {
+		title: "Deliveries",
+		description: "The global delivery log (every email and webhook attempted, with status progression) plus the public SES feedback and one-click unsubscribe endpoints.",
+		intro: "Each send attempt creates a delivery. A delivery is `sent` then `delivered`, `bounced` or `complained`, or it is `failed`, a typed `skipped_*`, or a dry-run `would_*`. Status precedence ensures that a late `delivered` status never overwrites `bounced`, and a complaint outranks a bounce. For webhooks, a successful response confirms delivery, making `delivered` terminal. Public routes for delivery feedback and RFC 8058 one-click unsubscribe verify signatures instead of sessions, answering per the caller's convention rather than the standard envelope. Address verification is on the [emails](/reference/api/emails/) page."
+	},
+	emails: {
+		title: "Emails",
+		description: "The public email-address verification pages: the signed link in a verification email, answered as HTML.",
+		intro: "These routes handle direct transactional email sending and public email-address verification. The `emails.send` route is the first-party shape of the same send the [Resend facade](/resend/) serves, authenticating with an org API key and answering in the envelope with the delivery id. The public verification routes require no Cowliss credentials and answer with HTML pages rather than the envelope. Verification links authorize through a single-use `?token=` that expires after 48 hours, and an invalid, expired, or already-spent token is rejected. The `GET` request only offers the verification and the `POST` request performs it, so a link scanner that fetches the URL does not verify the address."
+	},
+	suppressions: {
+		title: "Suppressions",
+		description: "Cowliss's mirror of your organization's suppression list: the cheap send-gate check and the dashboard's why.",
+		intro: "Cowliss mirrors the suppression list your organization accumulates from hard bounces and complaints per address so the send gate skips cheaply and the dashboard can say why. Suppression is a separate fact from [consent](/reference/api/consent/): a complaint revokes consent, while a bounce only suppresses the address. The list is your organization's own: an address one organization suppresses is untouched for every other."
+	},
+	settings: {
+		title: "Settings",
+		description: "Org settings: ingestion policy, event retention, the sending-pause state, and self-service org API keys and pipeline keys.",
+		intro: "Organization settings configure data handling: `ingestionPolicy` decides whether unclassified event and trait names are accepted and flagged or quarantined for review, `eventRetentionDays` keeps events for at most 18 months, and `sendingPaused` is a platform pause that the organization can read but only the platform sets. This module is also the self-service home of the organization's two key families: ingestion API keys, which write events and reach nothing else, and pipeline keys, which push an app and reach nothing else. Any member can list either family, but only admins create and revoke them. Neither list shows the other family's keys, and revoking a key from the other family cannot find it. See the [Keys guide](/guides/keys/)."
+	},
+	billing: {
+		title: "Billing",
+		description: "The prepaid wallet: metered spend against the monthly free allowance, fixed-amount Stripe top-ups, and the hard stop at zero credit.",
+		intro: "Spend is one weighted total over events, emails, webhooks and journey runs, counted from what already happened, never billed in arrears. Credit is the monthly included usage (" + dollars(FREE_ALLOWANCE_MICROS) + ", resets each UTC month, no rollover) plus the prepaid wallet (carries over). At zero credit, the platform hard-stops: ingestion is refused and sends are skipped. See the [Billing guide](/guides/billing/)."
+	},
+	openapi: {
+		title: "OpenAPI",
+		description: "The OpenAPI 3.1 document, built from this contract.",
+		intro: "The document is built from the route contract. Requests to `GET /openapi.json` are served unauthenticated."
+	},
+	me: {
+		title: "Me",
+		description: "The signed-in developer's own settings.",
+		intro: "These routes manage the signed-in developer's own settings. Like the rest of the dashboard API, requests use session authentication, but this resource is deliberately not org-scoped: the subject is the caller's own platform-workspace profile, taken from the session, never from the request. They are hidden from the CLI and the MCP server because both act with an organization key on that organization's data without a signed-in human. An operator changing an end user's consent uses `users.updateConsent` instead, which is the same decision made by someone else."
+	},
+	resend: {
+		title: "Resend-compatible send",
+		description: "The Resend-compatible send facade: point `RESEND_BASE_URL` at `/resend/{appOrSourceId}` and keep your code.",
+		intro: "The Resend-compatible send facade lets developers point `RESEND_BASE_URL` at `/resend/{appOrSourceId}` and keep their code. The `appOrSourceId` path segment accepts an app id or the id of its API source, because the Resend SDK carries no other field and accepts no custom header. The bearer is the organization's ingestion key. Every send creates a delivery and requires a from-address on a domain the organization has verified. These routes answer Resend's own shapes rather than the envelope."
+	}
+};
+
+//#endregion
+//#region ../../packages/shared/src/contract/templates.ts
+/**
+* Templates, addressed by key like a journey. No create and no update: a
+* template has versions and nothing else (ADR 0011). What `preview` and
+* `testSend` do is the `templates` intro in `tags.ts`.
 */
 const params$3 = z.object({ key: z.string() });
 const templates = defineModule(defineRoute({
@@ -11408,6 +11626,7 @@ const templates = defineModule(defineRoute({
 	operationId: "templates.testSend",
 	tags: ["templates"],
 	summary: "Send a rendered template to your own address",
+	description: "Sends through your organization's default sender. The test goes to you regardless of your consent settings, costs nothing, and shows as a test.",
 	security: SESSION_AUTH,
 	request: {
 		params: params$3,
@@ -11424,6 +11643,7 @@ const templates = defineModule(defineRoute({
 	operationId: "templates.delete",
 	tags: ["templates"],
 	summary: "Delete an email template",
+	description: "Admin only. Deleting a key deletes every version of it and is refused while a journey still sends it, naming the journeys.",
 	security: SESSION_AUTH,
 	request: { params: params$3 },
 	responses: {
@@ -11504,6 +11724,7 @@ const users = defineModule(defineRoute({
 	operationId: "users.eraseByIdentifier",
 	tags: ["users"],
 	summary: "Erase every person one identifier names (GDPR)",
+	description: "Admin only. Terminates active journey executions, then permanently deletes every profile across your apps that carries the identifier, along with their merged profiles, and their event and delivery history. This action cannot be undone.",
 	security: SESSION_AUTH,
 	request: { body: jsonBody(eraseUserByIdentifierBodySchema) },
 	responses: {
@@ -11531,6 +11752,7 @@ const users = defineModule(defineRoute({
 	operationId: "users.erase",
 	tags: ["users"],
 	summary: "Erase a user (GDPR)",
+	description: "Admin only. Terminates active journey executions, then permanently deletes the profile, any profiles merged into it, and their event and delivery history. This action cannot be undone.",
 	security: SESSION_AUTH,
 	request: { params: params$2 },
 	responses: {
@@ -11651,6 +11873,7 @@ const violations = defineModule(defineRoute({
 	operationId: "violations.resolve",
 	tags: ["violations"],
 	summary: "Resolve a violation into the catalog",
+	description: "Admin only. Resolving is irreversible and refuses violations that have already been handled or whose name is already in the catalog. You must supply `data.type` when resolving a trait that was only observed as `null`.",
 	security: SESSION_AUTH,
 	request: {
 		params: params$1,
@@ -11667,6 +11890,7 @@ const violations = defineModule(defineRoute({
 	operationId: "violations.dismiss",
 	tags: ["violations"],
 	summary: "Dismiss a violation",
+	description: "Admin only. Dismissing is irreversible and refuses violations that have already been handled. Future sightings of the name continue to be accepted but do not flag new violations.",
 	security: SESSION_AUTH,
 	request: { params: params$1 },
 	responses: {
@@ -11724,6 +11948,7 @@ const webhooks = defineModule(defineRoute({
 	operationId: "webhooks.update",
 	tags: ["webhooks"],
 	summary: "Update a webhook",
+	description: "Setting `enabled` to `true` re-enables an auto-disabled webhook and resets its consecutive failure counter to zero. Setting `enabled` to `false` disables the webhook manually.",
 	security: SESSION_AUTH,
 	request: {
 		params,
@@ -12136,6 +12361,7 @@ function cliCommandFor(route, moduleKey) {
 		groups: segments.slice(0, -1),
 		verb,
 		summary: route.summary ?? route.operationId,
+		description: route.description,
 		positionals: pathParams(route),
 		queryOptions: queryOptions(route),
 		bodyOptions: body,
@@ -12150,7 +12376,8 @@ function shapeKeys(schema) {
 function mcpToolFor(route, moduleKey) {
 	assertNoHeaders(route);
 	const name = route.surfaces?.mcpName ?? route.operationId.replaceAll(".", "_");
-	const description = route.surfaces?.description ?? route.summary ?? route.operationId;
+	const summary = route.summary ?? route.operationId;
+	const description = route.surfaces?.description ?? (route.description ? `${summary}\n\n${route.description}` : summary);
 	const data = bodyDataSchema(route);
 	const rawBody = data !== void 0 && !(data instanceof z.ZodObject);
 	const bodyKeys = data === void 0 ? [] : data instanceof z.ZodObject ? Object.keys(data.shape) : ["data"];
@@ -12304,7 +12531,7 @@ function groupFor(program, groups, segments) {
 		const segment = segments[depth - 1];
 		let group = groups.get(key);
 		if (!group) {
-			group = parent.command(segment).description(segment);
+			group = parent.command(segment).description(depth === 1 && Object.hasOwn(TAG_DOCS, segment) ? TAG_DOCS[segment].description : segment);
 			groups.set(key, group);
 		}
 		parent = group;
@@ -12318,6 +12545,7 @@ function registerContractCommands(program, run) {
 	const requestOf = (client) => client.request;
 	for (const spec of plan.cli) {
 		const command = groupFor(program, groups, spec.groups).command([spec.verb, ...spec.positionals.map((name) => `<${name}>`)].join(" ")).description(spec.summary);
+		if (spec.description) command.addHelpText("after", `\n${spec.description}`);
 		for (const option of [...spec.queryOptions, ...spec.bodyOptions]) registerOption(command, option);
 		command.action(async (...args) => {
 			const positionals = args.slice(0, spec.positionals.length);
@@ -12482,6 +12710,42 @@ function registerEnable(program, clientFor, io) {
 	register(program, clientFor, io, "pause", "paused");
 }
 
+//#endregion
+//#region src/commands/events.ts
+/** `cow events --help` and the `events_prompt` MCP tool, in one place. */
+const eventsDescription = {
+	cli: "instructions for a coding agent to send the events this app's journeys need",
+	mcp: "Instructions for a coding agent to send the events this app's journeys need. Reads the local project; calls no API."
+};
+async function projectEventsPrompt(dir) {
+	const projectDir = dir ?? resolveProjectDir();
+	const { manifest } = await buildProject(projectDir);
+	const items = manifest.events.map((evt) => ({ name: evt.pattern }));
+	return buildEventsPrompt({
+		events: items,
+		sdkPackage: "@cowliss/sdk",
+		trackMethod: "cow.track",
+		referenceUrl: `${DOCS_URL}/sdk/track/`
+	});
+}
+function registerEvents(program, io) {
+	let eventsCmd = program.commands.find((c) => c.name() === "events");
+	if (!eventsCmd) eventsCmd = program.command("events");
+	eventsCmd.description(eventsDescription.cli);
+	eventsCmd.action(async (opts) => {
+		const merged = {
+			...program.opts(),
+			...opts
+		};
+		const prompt = await projectEventsPrompt();
+		if (merged.json === true) {
+			emit({ data: { prompt } }, io, true);
+			return;
+		}
+		io.stdout(`${prompt}\n`);
+	});
+}
+
 //#endregion
 //#region src/commands/init.ts
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
@@ -13085,6 +13349,11 @@ function registerPush(program, clientFor, env, io) {
 * `unseenReport`. There is no second computation that could drift from the
 * one the push itself shows.
 */
+/** `cow plan --help` and the `pushes_plan` MCP tool, in one place. */
+const planDescription = {
+	cli: "show what a push of this repository would change, and change nothing",
+	mcp: "What a push of the project in the current directory would change. Builds locally; uploads and stores nothing."
+};
 /** The envelope `cow plan --json` prints, and what the MCP tool answers. */
 async function projectPlan(client) {
 	const { plan } = await planProject({
@@ -13094,7 +13363,7 @@ async function projectPlan(client) {
 	return { data: plan };
 }
 function registerPlan(program, clientFor, io) {
-	program.command("plan").description("show what a push of this repository would change, and change nothing").action(async (opts) => {
+	program.command("plan").description(planDescription.cli).action(async (opts) => {
 		const merged = {
 			...program.opts(),
 			...opts
@@ -13195,9 +13464,28 @@ async function createMcpServer({ client }) {
 		inputSchema: tool.inputSchema
 	}, async (args) => toolResult(() => tool.route.request ? request(tool.route, tool.toInput(args)) : request(tool.route)));
 	server.registerTool("pushes_plan", {
-		description: "What a push of the project in the current directory would change. Builds locally; uploads and stores nothing.",
+		description: planDescription.mcp,
 		inputSchema: {}
 	}, async () => toolResult(() => projectPlan(client)));
+	server.registerTool("events_prompt", {
+		description: eventsDescription.mcp,
+		inputSchema: {}
+	}, async () => {
+		try {
+			return { content: [{
+				type: "text",
+				text: await projectEventsPrompt()
+			}] };
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: errorMessage$1(error)
+				}],
+				isError: true
+			};
+		}
+	});
 	return server;
 }
 function errorMessage$1(error) {
@@ -13615,6 +13903,7 @@ function buildProgram(env, io) {
 		emit(await fn(await clientFor(merged)), io, typeof merged.json === "boolean" ? merged.json : void 0);
 	};
 	registerContractCommands(program, run);
+	registerEvents(program, io);
 	registerAuth(program, env, io);
 	registerInit(program, clientFor, env, io);
 	registerAdd(program, io);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cowliss/cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "bin": {
     "cow": "./dist/index.js"