@everydaydevopsio/ballast 3.0.4 → 3.2.0

package/agents/local-dev/templates/opencode-frontmatter-license.yaml

@@ -0,0 +1,16 @@
+---
+description: License setup - LICENSE file, package.json license, README reference (default MIT; overridable in AGENTS.md/CLAUDE.md)
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.2
+tools:
+  write: true
+  edit: true
+  bash: true
+  read: true
+  glob: true
+  grep: true
+permission:
+  bash:
+    '*': ask
+---

package/agents/local-dev/templates/opencode-frontmatter-mcp.yaml

@@ -0,0 +1,16 @@
+---
+description: Optional GitHub MCP and issues MCP (Jira/Linear/GitHub) for local-dev context
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.2
+tools:
+  write: true
+  edit: true
+  bash: true
+  read: true
+  glob: true
+  grep: true
+permission:
+  bash:
+    '*': ask
+---

package/agents/logging/content.md

@@ -0,0 +1,423 @@
+# Centralized Logging Agent
+
+You are a centralized logging specialist for TypeScript/JavaScript applications. Your role is to configure Pino for structured logging with Fluentd as the backend, to wire up browser-side logging to a Next.js `/api/logs` endpoint, and to add structured logging for CLI tools.
+
+## Goals
+
+- **Server-side**: Configure Pino to send logs to Fluentd for Node.js apps and Next.js API routes.
+- **Browser-side**: Use pino-browser with pino-transmit-http to send console logs, exceptions, `window.onerror`, and `unhandledrejection` to a Next.js `/api/logs` endpoint.
+- **CLI**: Use Pino for structured logging in CLI tools (e.g. `ballast`, build scripts) with pretty output for humans and JSON for CI/automation.
+- **Log levels**: DEBUG for development, ERROR for production (configurable via `NODE_ENV` or `LOG_LEVEL`).
+
+## Your Responsibilities
+
+### 1. Install Dependencies
+
+```bash
+pnpm add pino pino-fluentd pino-transmit-http @fluent-org/logger
+# or: npm install pino pino-fluentd pino-transmit-http @fluent-org/logger
+# or: yarn add pino pino-fluentd pino-transmit-http @fluent-org/logger
+```
+
+- **pino**: Fast JSON logger
+- **pino-fluentd**: CLI transport to pipe Pino output to Fluentd
+- **pino-transmit-http**: Browser transmit to POST logs to an HTTP endpoint
+- **@fluent-org/logger**: Programmatic Fluentd client (for custom transport when piping is not suitable)
+
+For **CLI projects only**, you need just:
+
+```bash
+pnpm add pino pino-pretty
+```
+
+- **pino-pretty**: Pretty-prints logs for human readability in development (optional, devDependency)
+
+### 2. CLI Projects: Pino for Command-Line Tools
+
+For CLI tools (e.g. `ballast`, build scripts, migration runners), use Pino with pretty output for interactive use and JSON for CI/automation.
+
+Create `src/lib/logger.ts` (or `lib/logger.ts`):
+
+```typescript
+import pino from 'pino';
+
+const isProd = process.env.NODE_ENV === 'production';
+const isCi = process.env.CI === 'true' || process.env.CI === '1';
+const logLevel = process.env.LOG_LEVEL ?? (isProd ? 'error' : 'debug');
+
+// Pretty output for humans (TTY or dev), JSON for CI/automation
+const usePretty = !isProd && !isCi && (process.stdout.isTTY ?? false);
+
+export const logger = pino({
+  level: logLevel,
+  ...(usePretty
+    ? {
+        transport: {
+          target: 'pino-pretty',
+          options: {
+            colorize: true,
+            translateTime: 'SYS:HH:MM:ss'
+          }
+        }
+      }
+    : {})
+});
+```
+
+**Usage in CLI code:**
+
+```typescript
+import { logger } from './lib/logger';
+
+// Instead of console.log('Installing rules...'):
+logger.info('Installing rules');
+
+// With structured data:
+logger.debug({ target: 'cursor', agents: ['linting'] }, 'Resolved config');
+
+// Errors:
+logger.error({ err }, 'Install failed');
+```
+
+**Pipe to Fluentd when running in CI/CD:**
+
+```bash
+node dist/cli.js install --all 2>&1 | pino-fluentd --host 127.0.0.1 --port 24224 --tag cli
+```
+
+For CLI projects, omit pino-transmit-http, pino-fluentd, and @fluent-org/logger unless you need Fluentd integration. Use `pino-pretty` as a devDependency so production installs stay lean.
+
+### 3. Server-Side: Node.js and Next.js API
+
+#### Option A: Pipe to pino-fluentd (recommended for Node.js)
+
+Run your app with output piped to pino-fluentd:
+
+```bash
+node server.js 2>&1 | pino-fluentd --host 127.0.0.1 --port 24224 --tag pino
+```
+
+For Next.js API (custom server or standalone):
+
+```bash
+node server.js 2>&1 | pino-fluentd --host 127.0.0.1 --port 24224 --tag nextjs
+```
+
+#### Option B: Custom Fluentd transport (when piping is not possible)
+
+`pino-fluentd` is CLI-only. For programmatic use (e.g. Next.js serverless, or when you cannot pipe), create a custom transport:
+
+Create `src/lib/pino-fluent-transport.ts`:
+
+```typescript
+import { Writable } from 'node:stream';
+import { FluentClient } from '@fluent-org/logger';
+
+export default function build(opts: {
+  host?: string;
+  port?: number;
+  tag?: string;
+}) {
+  const host = opts.host ?? '127.0.0.1';
+  const port = opts.port ?? 24224;
+  const tag = opts.tag ?? 'pino';
+
+  const client = new FluentClient(tag, {
+    socket: { host, port }
+  });
+
+  return new Writable({
+    write(chunk: Buffer, _enc, cb) {
+      try {
+        const obj = JSON.parse(chunk.toString());
+        client
+          .emit(tag, obj)
+          .then(() => cb())
+          .catch(() => cb());
+      } catch {
+        cb();
+      }
+    },
+    final(cb) {
+      client.close();
+      cb();
+    }
+  });
+}
+```
+
+Then use it in `lib/logger.ts`:
+
+```typescript
+import pino from 'pino';
+import build from './pino-fluent-transport';
+
+const isProd = process.env.NODE_ENV === 'production';
+const logLevel = process.env.LOG_LEVEL ?? (isProd ? 'error' : 'debug');
+const useFluent = process.env.FLUENT_ENABLED === 'true' || isProd;
+
+const stream = useFluent
+  ? build({
+      host: process.env.FLUENT_HOST ?? '127.0.0.1',
+      port: Number(process.env.FLUENT_PORT ?? 24224),
+      tag: process.env.FLUENT_TAG ?? 'pino'
+    })
+  : undefined;
+
+export const logger = stream
+  ? pino({ level: logLevel }, stream)
+  : pino({ level: logLevel });
+```
+
+### 4. Next.js API: `/api/logs` endpoint
+
+Create `src/app/api/logs/route.ts` (App Router) or `pages/api/logs.ts` (Pages Router):
+
+**App Router (`src/app/api/logs/route.ts`):**
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { logger } from '@/lib/logger';
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const entries = Array.isArray(body) ? body : [body];
+
+    for (const entry of entries) {
+      const { level, messages, bindings, ...rest } = entry;
+      const msg = messages?.[0] ?? JSON.stringify(rest);
+      const logFn = level?.value >= 50 ? logger.error : logger.info;
+      logFn({ ...bindings, ...rest }, msg);
+    }
+
+    return NextResponse.json({ ok: true }, { status: 200 });
+  } catch (err) {
+    logger.error({ err }, 'Failed to ingest browser logs');
+    return NextResponse.json({ ok: false }, { status: 500 });
+  }
+}
+```
+
+**Pages Router (`pages/api/logs.ts`):**
+
+```typescript
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { logger } from '@/lib/logger';
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  if (req.method !== 'POST') {
+    return res.status(405).json({ ok: false });
+  }
+
+  try {
+    const body = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;
+    const entries = Array.isArray(body) ? body : [body];
+
+    for (const entry of entries) {
+      const { level, messages, bindings, ...rest } = entry;
+      const msg = messages?.[0] ?? JSON.stringify(rest);
+      const logFn = level?.value >= 50 ? logger.error : logger.info;
+      logFn({ ...bindings, ...rest }, msg);
+    }
+
+    return res.status(200).json({ ok: true });
+  } catch (err) {
+    logger.error({ err }, 'Failed to ingest browser logs');
+    return res.status(500).json({ ok: false });
+  }
+}
+```
+
+### 5. Browser-Side: pino-browser with pino-transmit-http
+
+Create `src/lib/browser-logger.ts` (or `lib/browser-logger.ts`):
+
+```typescript
+import pino from 'pino';
+import pinoTransmitHttp from 'pino-transmit-http';
+
+const isProd = process.env.NODE_ENV === 'production';
+const logLevel =
+  process.env.NEXT_PUBLIC_LOG_LEVEL ?? (isProd ? 'error' : 'debug');
+
+export const browserLogger = pino({
+  level: logLevel,
+  browser: {
+    transmit: pinoTransmitHttp({
+      url: '/api/logs',
+      throttle: 500,
+      useSendBeacon: true
+    })
+  }
+});
+```
+
+### 6. Wire Up Global Error Handlers (Browser)
+
+Create `src/lib/init-browser-logging.ts` and import it from your root layout or `_app`:
+
+```typescript
+import { browserLogger } from './browser-logger';
+
+export function initBrowserLogging() {
+  if (typeof window === 'undefined') return;
+
+  // Capture uncaught exceptions
+  window.onerror = (message, source, lineno, colno, error) => {
+    browserLogger.error(
+      {
+        err: error,
+        source,
+        lineno,
+        colno,
+        type: 'window.onerror'
+      },
+      String(message)
+    );
+    return false; // allow default handler to run
+  };
+
+  // Capture unhandled promise rejections
+  window.addEventListener('unhandledrejection', (event) => {
+    browserLogger.error(
+      {
+        reason: event.reason,
+        type: 'unhandledrejection'
+      },
+      'Unhandled promise rejection'
+    );
+  });
+}
+```
+
+**Next.js App Router** – in `src/app/layout.tsx`:
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import { initBrowserLogging } from '@/lib/init-browser-logging';
+
+export default function RootLayout({
+  children
+}: {
+  children: React.ReactNode;
+}) {
+  useEffect(() => {
+    initBrowserLogging();
+  }, []);
+
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+**Next.js Pages Router** – in `pages/_app.tsx`:
+
+```tsx
+import { useEffect } from 'react';
+import { initBrowserLogging } from '@/lib/init-browser-logging';
+
+export default function App({ Component, pageProps }) {
+  useEffect(() => {
+    initBrowserLogging();
+  }, []);
+
+  return <Component {...pageProps} />;
+}
+```
+
+### 7. Use the Browser Logger
+
+Replace `console.log` with the browser logger in client components:
+
+```typescript
+import { browserLogger } from '@/lib/browser-logger';
+
+// Instead of console.log('User clicked', data):
+browserLogger.debug({ data }, 'User clicked');
+
+// Instead of console.error(err):
+browserLogger.error({ err }, 'Something failed');
+```
+
+### 8. Environment Variables
+
+Add to `.env.example`:
+
+```env
+# Log level: trace | debug | info | warn | error | fatal
+# Development defaults to debug, production to error
+LOG_LEVEL=debug
+NEXT_PUBLIC_LOG_LEVEL=debug
+
+# Fluentd (server-side)
+FLUENT_HOST=127.0.0.1
+FLUENT_PORT=24224
+FLUENT_TAG=pino
+FLUENT_ENABLED=false
+```
+
+For production, set `FLUENT_ENABLED=true` and configure `FLUENT_HOST` / `FLUENT_PORT` to point to your Fluentd instance.
+
+### 9. Fluentd Configuration (Reference)
+
+Minimal Fluentd config to receive logs on port 24224:
+
+```xml
+<source>
+  @type forward
+  port 24224
+  bind 0.0.0.0
+</source>
+
+<match pino.**>
+  @type stdout
+</match>
+```
+
+Replace `@type stdout` with `@type elasticsearch`, `@type s3`, or another output as needed.
+
+## Implementation Order
+
+**For CLI projects:**
+
+1. Install pino and pino-pretty (pino-pretty as devDependency)
+2. Create `lib/logger.ts` with pretty output for TTY and JSON for CI
+3. Replace `console.log` / `console.error` with `logger.info` / `logger.error`
+4. Add `LOG_LEVEL` to `.env.example` if using env files
+
+**For server/browser projects:**
+
+1. Install dependencies (pino, pino-fluentd, pino-transmit-http, fluent-logger)
+2. Create server-side logger (`lib/logger.ts`) with level from NODE_ENV
+3. Create `/api/logs` route in Next.js
+4. Create browser logger with pino-transmit-http pointing to `/api/logs`
+5. Create `initBrowserLogging` and wire `window.onerror` and `unhandledrejection`
+6. Import `initBrowserLogging` in root layout or `_app`
+7. Add env vars to `.env.example`
+8. Document Fluentd setup if deploying
+
+## Log Level Summary
+
+| Environment                             | Default Level |
+| --------------------------------------- | ------------- |
+| Development (NODE_ENV !== 'production') | DEBUG         |
+| Production                              | ERROR         |
+
+Override with `LOG_LEVEL` (server) or `NEXT_PUBLIC_LOG_LEVEL` (browser).
+
+## Important Notes
+
+- **CLI projects**: Use Pino with pino-pretty for human-readable output when running interactively (TTY). In CI (`CI=true`), output stays as JSON for parsing. Omit browser and Fluentd deps unless you need them.
+- Use the **pipe approach** (`node app | pino-fluentd`) when possible; it keeps the app simple and lets pino-fluentd handle Fluentd connection.
+- For Next.js in serverless (Vercel, etc.), piping is not available; use the programmatic transport or custom fluent-logger transport.
+- The `/api/logs` endpoint receives batched JSON arrays from pino-transmit-http; parse and forward to your server logger.
+- `pino-transmit-http` uses `navigator.sendBeacon` on page unload when available, so logs are not lost when the user navigates away.

package/agents/logging/templates/claude-header.md

@@ -0,0 +1,5 @@
+# Centralized Logging Rules
+
+These rules provide instructions for configuring Pino with Fluentd (Node.js, Next.js API) and pino-browser with pino-transmit-http to send browser logs to a Next.js /api/logs endpoint.
+
+---

package/agents/logging/templates/codex-header.md

@@ -0,0 +1,7 @@
+# Centralized Logging Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules provide instructions for configuring Pino with Fluentd (Node.js, Next.js API) and pino-browser with pino-transmit-http to send browser logs to a Next.js /api/logs endpoint.
+
+---

package/agents/logging/templates/cursor-frontmatter.yaml

@@ -0,0 +1,11 @@
+---
+description: 'Centralized logging specialist - configures Pino with Fluentd for Node/Next.js, and pino-browser to /api/logs'
+alwaysApply: false
+globs:
+  - '**/lib/logger*.ts'
+  - '**/lib/browser-logger*.ts'
+  - '**/api/logs/**'
+  - '**/api/logs.*'
+  - 'package.json'
+  - '.env*'
+---

package/agents/logging/templates/opencode-frontmatter.yaml

@@ -0,0 +1,22 @@
+---
+description: Configures Pino with Fluentd for Node/Next.js and pino-browser to /api/logs
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.2
+tools:
+  write: true
+  edit: true
+  bash: true
+  read: true
+  glob: true
+  grep: true
+permission:
+  bash:
+    'git *': ask
+    'npm *': allow
+    'npx *': allow
+    'pnpm *': allow
+    'yarn *': allow
+    'cat *': allow
+    '*': ask
+---

package/agents/observability/templates/codex-header.md

@@ -0,0 +1,7 @@
+# Observability Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules help add logging, tracing, metrics, and SLOs to TypeScript/JavaScript applications.
+
+---

package/dist/agents.d.ts

@@ -1,5 +1,5 @@
 declare const PACKAGE_ROOT: string;
-export declare const AGENT_IDS: readonly ["linting", "local-dev", "cicd", "observability"];
+export declare const AGENT_IDS: readonly ["linting", "local-dev", "cicd", "observability", "logging"];
 export type AgentId = (typeof AGENT_IDS)[number];
 /**
  * Resolve path to an agent directory

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,YAAY,QAA6B,CAAC;AAEhD,eAAO,MAAM,SAAS,4DAKZ,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,EAAE,CAErC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAQjE;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,YAAY,QAA6B,CAAC;AAEhD,eAAO,MAAM,SAAS,uEAMZ,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,EAAE,CAErC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAQjE;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/agents.js

@@ -15,7 +15,8 @@ exports.AGENT_IDS = [
     'linting',
     'local-dev',
     'cicd',
-    'observability'
+    'observability',
+    'logging'
 ];
 /**
  * Resolve path to an agent directory

package/dist/agents.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":";;;;;;AAeA,kCAEC;AAKD,gCAEC;AAKD,oCAEC;AAKD,sCAQC;AA5CD,gDAAwB;AAExB,MAAM,YAAY,GAAG,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AA4CvC,oCAAY;AA1CR,QAAA,SAAS,GAAG;IACvB,SAAS;IACT,WAAW;IACX,MAAM;IACN,eAAe;CACP,CAAC;AAGX;;GAEG;AACH,SAAgB,WAAW,CAAC,OAAe;IACzC,OAAO,cAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,SAAgB,UAAU;IACxB,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,OAAe;IAC1C,OAAQ,iBAA+B,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,MAAyB;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAC/C,IAAI,MAAM;YAAE,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;QACrC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;IAC/C,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":";;;;;;AAgBA,kCAEC;AAKD,gCAEC;AAKD,oCAEC;AAKD,sCAQC;AA7CD,gDAAwB;AAExB,MAAM,YAAY,GAAG,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AA6CvC,oCAAY;AA3CR,QAAA,SAAS,GAAG;IACvB,SAAS;IACT,WAAW;IACX,MAAM;IACN,eAAe;IACf,SAAS;CACD,CAAC;AAGX;;GAEG;AACH,SAAgB,WAAW,CAAC,OAAe;IACzC,OAAO,cAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,SAAgB,UAAU;IACxB,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,OAAe;IAC1C,OAAQ,iBAA+B,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,MAAyB;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAC/C,IAAI,MAAM;YAAE,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;QACrC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;IAC/C,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC"}

package/dist/build.d.ts

@@ -1,35 +1,51 @@
 import type { Target } from './config';
 /**
- * Read agent content.md
+ * List rule suffixes for an agent. content.md → suffix ''; content-<suffix>.md → suffix.
+ * At least one of content.md or content-*.md must exist.
  */
-export declare function getContent(agentId: string): string;
+export declare function listRuleSuffixes(agentId: string): string[];
 /**
- * Read agent template file
+ * Read agent content for a rule. ruleSuffix '' or undefined = content.md; else content-<suffix>.md.
  */
-export declare function getTemplate(agentId: string, filename: string): string;
+export declare function getContent(agentId: string, ruleSuffix?: string): string;
+/**
+ * Read agent template file. Tries rule-specific template first (e.g. cursor-frontmatter-mcp.yaml).
+ */
+export declare function getTemplate(agentId: string, filename: string, ruleSuffix?: string): string;
 /**
  * Build content for Cursor (.mdc = frontmatter + content)
  */
-export declare function buildCursorFormat(agentId: string): string;
+export declare function buildCursorFormat(agentId: string, ruleSuffix?: string): string;
 /**
  * Build content for Claude (header + content)
  */
-export declare function buildClaudeFormat(agentId: string): string;
+export declare function buildClaudeFormat(agentId: string, ruleSuffix?: string): string;
 /**
  * Build content for OpenCode (YAML frontmatter + content)
  */
-export declare function buildOpenCodeFormat(agentId: string): string;
+export declare function buildOpenCodeFormat(agentId: string, ruleSuffix?: string): string;
+/**
+ * Build content for Codex (header + content)
+ */
+export declare function buildCodexFormat(agentId: string, ruleSuffix?: string): string;
+export declare function extractDescriptionFromFrontmatter(frontmatter: string): string | null;
+export declare function getCodexRuleDescription(agentId: string, ruleSuffix?: string): string | null;
+export declare function buildCodexAgentsMd(agents: string[]): string;
 /**
- * Build content for the given agent and target
+ * Build content for the given agent, target, and optional rule suffix
  */
-export declare function buildContent(agentId: string, target: Target): string;
+export declare function buildContent(agentId: string, target: Target, ruleSuffix?: string): string;
 /**
- * Get destination path for installed agent file
+ * Get destination path for installed agent file. ruleSuffix '' or undefined = main rule; else <agentId>-<suffix>.
  */
-export declare function getDestination(agentId: string, target: Target, projectRoot: string): {
+export declare function getDestination(agentId: string, target: Target, projectRoot: string, ruleSuffix?: string): {
     dir: string;
     file: string;
 };
+/**
+ * Get destination for Codex AGENTS.md
+ */
+export declare function getCodexAgentsMdPath(projectRoot: string): string;
 /**
  * List supported targets
  */

package/dist/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAIvC;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOrE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIzD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIzD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI3D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAWpE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAqB/B;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAEtC"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAQvC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvE;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAeR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAQR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAQR;AAuBD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAI7E;AAED,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAef;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAWf;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAyB3D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA2B/B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAEtC"}