@moda-ai/cli 1.10.2 → 1.12.0

package/dist/skills.js

@@ -17,16 +17,17 @@
 // previous Moda pull wrote.
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, } from 'node:fs';
-import { basename, dirname, isAbsolute, join, normalize, relative, resolve } from 'node:path';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
 import { callControlAPI } from './api-client.js';
+import { createCommandContext } from './command-context.js';
 import { resolveApiKey, resolveIngestUrl, resolveTenantId } from './config.js';
 import { claudeSkillToCursorRule } from './init/rules.js';
 import { detectAgents } from './init/mcp.js';
+import { SKILL_SOURCE_HARNESS, SKILL_SOURCE_INTEGRATION_BUNDLED, pruneManagedSkillPaths, readSkillsManifest, writeSkillsManifest, } from './skills-manifest.js';
 import { CliInputError } from './errors.js';
 const SKILLS_REQUEST_TIMEOUT_MS = 15_000;
 const VALID_STATUSES = new Set(['approved', 'proposed', 'all']);
-const SKILLS_MANIFEST_PATH = join('.moda', 'skills.yml');
 const SKILL_PROPOSALS_MANIFEST_PATH = join('.moda', 'skill-proposals.yml');
 /**
  * Fetch a tenant's generated skills from the ingest worker. Uses the persisted
@@ -121,10 +122,18 @@ export async function pullSkills(options = {}) {
         return summary;
     }
     const previousManifest = readSkillsManifest(cwd);
+    // A release change only invalidates harness-generated skills. Paths owned
+    // by integration-bundled records are CLI-managed and must never be pruned
+    // by a harness release change (cross-source regression guard).
+    const preservedIntegrationRecords = (previousManifest?.records ?? []).filter((record) => record.source === SKILL_SOURCE_INTEGRATION_BUNDLED);
     if (previousManifest &&
         previousManifest.managedPaths.length > 0 &&
         previousManifest.releaseKey !== fetched.releaseKey) {
-        summary.pruned = pruneManagedSkillPaths(cwd, previousManifest.managedPaths, log);
+        const integrationPaths = new Set(preservedIntegrationRecords.flatMap((record) => record.paths));
+        const harnessPaths = previousManifest.managedPaths.filter((path) => !integrationPaths.has(path));
+        if (harnessPaths.length > 0) {
+            summary.pruned = pruneManagedSkillPaths(cwd, harnessPaths, log);
+        }
     }
     // Always target Claude Code (canonical SKILL.md). Also write Cursor rules
     // when the project has a .cursor directory.
@@ -166,11 +175,12 @@ export async function pullSkills(options = {}) {
             records.push({
                 skillId: safeId,
                 contentHash: sha256(skill.skill_md),
+                source: SKILL_SOURCE_HARNESS,
                 paths,
             });
         }
     }
-    writeSkillsManifest(cwd, fetched, records);
+    writeSkillsManifest(cwd, manifestHeaderFor(fetched), [...records, ...preservedIntegrationRecords]);
     return summary;
 }
 function recordOutcome(summary, status, log, relativePath) {
@@ -427,16 +437,26 @@ function escapeYamlString(value) {
 function formatProposalRate(value) {
     return `${(Number(value || 0) * 100).toFixed(1)}%`;
 }
-/**
- * `moda skills <subcommand>` dispatcher.
- */
-export async function runSkillsCommand(args) {
-    const sub = args.positional;
-    const positionals = args.positionals ?? (sub ? [sub] : []);
+export async function runSkillsCommand(input) {
+    const context = 'output' in input
+        ? input
+        : createCommandContext({
+            command: input.command,
+            positional: input.positional,
+            positionals: input.positionals,
+            flags: input.flags,
+        }, {
+            outputMode: input.flags.agent === 'true' ? 'agent' : input.flags.json === 'true' ? 'json' : 'human',
+        });
+    const sub = context.positional;
+    const positionals = context.positionals ?? (sub ? [sub] : []);
+    const flags = context.flags;
     if (sub === 'gen') {
-        const result = await generateSkills(args.flags);
-        if (args.flags.json === 'true') {
-            console.log(JSON.stringify(result));
+        const result = await generateSkills(flags);
+        if (context.outputMode !== 'human') {
+            context.output.writeData(result, {
+                status: Number(result.sessions_failed ?? 0) > 0 ? 'error' : 'success',
+            });
         }
         else if (result.accepted) {
             console.log([
@@ -458,8 +478,8 @@ export async function runSkillsCommand(args) {
         return Number(result.sessions_failed ?? 0) > 0 ? 1 : 0;
     }
     if (sub === 'proposals' && positionals[1] === 'list') {
-        const proposals = await fetchSkillProposals(args.flags, { profile: args.flags.profile });
-        if (args.flags.json === 'true') {
+        const proposals = await fetchSkillProposals(flags, { profile: context.profile });
+        if (flags.json === 'true') {
             console.log(JSON.stringify({ proposals }));
         }
         else if (proposals.length === 0) {
@@ -481,12 +501,12 @@ export async function runSkillsCommand(args) {
         return 0;
     }
     if (sub === 'proposal' && positionals[1] === 'apply') {
-        const proposalId = positionals[2] || args.flags['proposal-id'];
+        const proposalId = positionals[2] || flags['proposal-id'];
         if (!proposalId) {
             throw new CliInputError('A proposal id is required', 'Usage: moda skills proposal apply <proposal-id>');
         }
-        const result = await applySkillProposal(proposalId, args.flags, { profile: args.flags.profile });
-        if (args.flags.json === 'true') {
+        const result = await applySkillProposal(proposalId, flags, { profile: context.profile });
+        if (flags.json === 'true') {
             console.log(JSON.stringify(result));
         }
         else {
@@ -508,18 +528,18 @@ export async function runSkillsCommand(args) {
         return 0;
     }
     if (sub === 'sync') {
-        const result = await runSkillSync(args.flags, { profile: args.flags.profile });
-        console.log(JSON.stringify({ synced: result.synced, dryRun: result.dryRun }));
+        const result = await runSkillSync(flags, { profile: context.profile, env: context.env });
+        context.output.writeData({ synced: result.synced, dryRun: result.dryRun });
         return 0;
     }
     if (sub !== 'pull') {
         throw new CliInputError(sub ? `Unknown skills subcommand '${sub}'` : 'A skills subcommand is required', 'Usage: moda skills gen [--source=all|sdk|coding-agent] [--max-sessions=N] [--start-at=ISO] [--end-at=ISO] [--replay] [--replay-set-id=ID] [--reprocess-segments] [--force-reprocess] [--wait] | moda skills proposals list [--status=ready_for_pr] | moda skills proposal apply <proposal-id> | moda skills pull [--status=approved|proposed|all] | moda skills sync [--dry-run]');
     }
-    const status = (args.flags.status ?? 'approved').toLowerCase();
+    const status = (flags.status ?? 'approved').toLowerCase();
     if (!VALID_STATUSES.has(status)) {
         throw new CliInputError(`Invalid --status '${status}'`, `Must be one of: ${[...VALID_STATUSES].join(', ')}`);
     }
-    const summary = await pullSkills({ status });
+    const summary = await pullSkills({ status, silent: context.outputMode !== 'human' });
     const parts = [
         summary.pruned && `${summary.pruned} pruned`,
         summary.wrote && `${summary.wrote} written`,
@@ -527,9 +547,12 @@ export async function runSkillsCommand(args) {
         summary.unchanged && `${summary.unchanged} unchanged`,
         summary.failed && `${summary.failed} failed`,
     ].filter(Boolean);
-    if (summary.total > 0) {
+    if (context.outputMode === 'human' && summary.total > 0) {
         console.log(`  Done — ${parts.join(', ') || 'no changes'}`);
     }
+    if (context.outputMode !== 'human') {
+        context.output.writeData({ status, summary });
+    }
     return summary.failed > 0 ? 1 : 0;
 }
 async function generateSkills(flags) {
@@ -617,146 +640,17 @@ function releaseKeyFor(release, skills, status) {
         hash: sha256(skill.skill_md || ''),
     })).sort((a, b) => a.skill_id.localeCompare(b.skill_id))))}`;
 }
-function readSkillsManifest(cwd) {
-    const manifestPath = join(cwd, SKILLS_MANIFEST_PATH);
-    if (!existsSync(manifestPath))
-        return null;
-    let text = '';
-    try {
-        text = readFileSync(manifestPath, 'utf8');
-    }
-    catch {
-        return null;
-    }
+function manifestHeaderFor(fetched) {
+    const release = fetched.release;
     return {
-        tenantId: readYamlScalar(text, 'tenant_id'),
-        generationRunId: readYamlScalar(text, 'generation_run_id'),
-        generationVersion: Number(readYamlScalar(text, 'generation_version') || 0),
-        releaseKey: readYamlScalar(text, 'release_key'),
-        releasedAt: readYamlScalar(text, 'released_at'),
-        managedPaths: readManagedPaths(text),
+        tenantId: fetched.tenantId,
+        releaseKey: fetched.releaseKey,
+        statusFilter: fetched.status,
+        generationRunId: release?.generation_run_id || '',
+        generationVersion: Number(release?.generation_version || 0),
+        releasedAt: release?.released_at || '',
     };
 }
-function writeSkillsManifest(cwd, fetched, records) {
-    const manifestPath = join(cwd, SKILLS_MANIFEST_PATH);
-    const managedPaths = [...new Set(records.flatMap((record) => record.paths))].sort();
-    const release = fetched.release;
-    const lines = [
-        'version: 1',
-        'source: moda',
-        `tenant_id: ${yamlQuote(fetched.tenantId)}`,
-        `release_key: ${yamlQuote(fetched.releaseKey)}`,
-        `status_filter: ${yamlQuote(fetched.status)}`,
-        `generation_run_id: ${yamlQuote(release?.generation_run_id || '')}`,
-        `generation_version: ${Number(release?.generation_version || 0)}`,
-        `released_at: ${yamlQuote(release?.released_at || '')}`,
-        `installed_at: ${yamlQuote(new Date().toISOString())}`,
-        'managed_paths:',
-        ...managedPaths.map((path) => `  - ${yamlQuote(path)}`),
-        'skills:',
-        ...records.flatMap((record) => [
-            `  - skill_id: ${yamlQuote(record.skillId)}`,
-            `    content_hash: ${yamlQuote(record.contentHash)}`,
-            '    paths:',
-            ...record.paths.map((path) => `      - ${yamlQuote(path)}`),
-        ]),
-        '',
-    ];
-    mkdirSync(dirname(manifestPath), { recursive: true });
-    writeFileSync(manifestPath, lines.join('\n'));
-}
-function pruneManagedSkillPaths(cwd, managedPaths, log) {
-    let pruned = 0;
-    for (const rawPath of [...new Set(managedPaths)]) {
-        const safePath = safeManagedRelativePath(rawPath);
-        if (!safePath)
-            continue;
-        const absolutePath = absoluteManagedPath(cwd, safePath);
-        if (!absolutePath || !existsSync(absolutePath))
-            continue;
-        try {
-            unlinkSync(absolutePath);
-            pruned++;
-            log(`  pruned ${safePath}`);
-            pruneEmptyClaudeSkillDir(cwd, safePath);
-        }
-        catch {
-            // Best-effort cleanup. The following write pass can still repair files
-            // that remain writable.
-        }
-    }
-    return pruned;
-}
-function pruneEmptyClaudeSkillDir(cwd, relativePath) {
-    if (!relativePath.startsWith('.claude/skills/') || !relativePath.endsWith('/SKILL.md'))
-        return;
-    const dir = dirname(join(cwd, relativePath));
-    try {
-        if (existsSync(dir) && readdirSync(dir).length === 0) {
-            rmdirSync(dir);
-        }
-    }
-    catch {
-        // Empty-dir pruning is only cosmetic.
-    }
-}
-function absoluteManagedPath(cwd, relativePath) {
-    const abs = resolve(cwd, relativePath);
-    const root = resolve(cwd);
-    const rel = relative(root, abs);
-    if (rel.startsWith('..') || isAbsolute(rel))
-        return null;
-    return abs;
-}
-function safeManagedRelativePath(rawPath) {
-    if (!rawPath || rawPath.includes('\0') || isAbsolute(rawPath))
-        return null;
-    const normalized = normalize(rawPath).replace(/\\/g, '/');
-    if (normalized.startsWith('../') || normalized === '..' || normalized.includes('/../'))
-        return null;
-    const isClaudeSkill = normalized.startsWith('.claude/skills/') && normalized.endsWith('/SKILL.md');
-    const isCursorRule = normalized.startsWith('.cursor/rules/') && normalized.endsWith('.mdc');
-    return isClaudeSkill || isCursorRule ? normalized : null;
-}
-function readYamlScalar(text, key) {
-    const match = text.match(new RegExp(`^${key}:\\s*(.*?)\\s*$`, 'm'));
-    return match ? parseYamlScalar(match[1]) : '';
-}
-function readManagedPaths(text) {
-    const paths = [];
-    let inManagedPaths = false;
-    for (const line of text.split(/\r?\n/)) {
-        if (line.trim() === 'managed_paths:') {
-            inManagedPaths = true;
-            continue;
-        }
-        if (inManagedPaths && line.length > 0 && !line.startsWith(' '))
-            break;
-        if (!inManagedPaths)
-            continue;
-        const match = line.match(/^\s*-\s*(.*?)\s*$/);
-        if (match)
-            paths.push(parseYamlScalar(match[1]));
-    }
-    return paths.filter(Boolean);
-}
-function parseYamlScalar(raw) {
-    const value = raw.trim();
-    if (!value)
-        return '';
-    if (value.startsWith('"')) {
-        try {
-            return String(JSON.parse(value));
-        }
-        catch {
-            return value.replace(/^"|"$/g, '');
-        }
-    }
-    return value.replace(/^'|'$/g, '');
-}
-function yamlQuote(value) {
-    return JSON.stringify(value);
-}
 function sha256(input) {
     return createHash('sha256').update(input).digest('hex');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.10.2",
+  "version": "1.12.0",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {
@@ -12,17 +12,18 @@
     "dist/**/*.d.ts",
     "!dist/__tests__",
     "hooks/**",
-    "skills/**/SKILL.md",
+    "skills/**",
     "README.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsc",
+    "bundle:skills": "bun scripts/bundle-skills.ts",
+    "build": "bun run bundle:skills && tsc",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "bun run bundle:skills && vitest run",
     "test:watch": "vitest",
     "lint": "eslint ."
   },
@@ -52,6 +53,7 @@
   },
   "devDependencies": {
     "@moda/eslint-config": "*",
+    "@moda/integration-skills": "*",
     "@types/node": "^22.10.5",
     "eslint": "^9.17.0",
     "typescript": "^5.7.2",

package/skills/integration/index.json

@@ -0,0 +1,123 @@
+{
+  "schema_version": "moda.skill_index.v1",
+  "bundled_at": "2026-07-06T02:25:00.333Z",
+  "cli_version": "1.12.0",
+  "skills": [
+    {
+      "id": "integration-node-anthropic",
+      "version": "1.0.0",
+      "summary": "Auto-instrument @anthropic-ai/sdk client calls with Moda in a Node.js or TypeScript app; no per-call changes required.",
+      "targets": {
+        "language": "node",
+        "frameworks": [],
+        "providers": [
+          "anthropic"
+        ]
+      }
+    },
+    {
+      "id": "integration-node-generic",
+      "version": "1.0.0",
+      "summary": "General Moda SDK integration for a Node.js or TypeScript app when no specific framework or provider skill matches.",
+      "targets": {
+        "language": "node",
+        "frameworks": [],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-node-langchain",
+      "version": "1.0.0",
+      "summary": "Instrument a Node.js LangChain or LangGraph app with Moda: init before the framework, explicit conversation ids around every run.",
+      "targets": {
+        "language": "node",
+        "frameworks": [
+          "langchain"
+        ],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-node-openai",
+      "version": "1.0.0",
+      "summary": "Auto-instrument direct openai client calls with Moda in a Node.js or TypeScript app; no per-call changes required.",
+      "targets": {
+        "language": "node",
+        "frameworks": [],
+        "providers": [
+          "openai"
+        ]
+      }
+    },
+    {
+      "id": "integration-node-vercel-ai-sdk",
+      "version": "1.0.0",
+      "summary": "Instrument Vercel AI SDK calls (generateText, streamText, generateObject) with Moda telemetry in a Node.js or TypeScript app.",
+      "targets": {
+        "language": "node",
+        "frameworks": [
+          "vercel-ai-sdk"
+        ],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-python-anthropic",
+      "version": "1.0.0",
+      "summary": "Auto-instrument anthropic client calls with Moda in a Python app; no per-call changes required.",
+      "targets": {
+        "language": "python",
+        "frameworks": [],
+        "providers": [
+          "anthropic"
+        ]
+      }
+    },
+    {
+      "id": "integration-python-claude-agent-sdk",
+      "version": "1.0.0",
+      "summary": "Instrument Claude Agent SDK sessions (ClaudeSDKClient) with Moda via the dedicated moda-claude-agent-sdk instrumentor.",
+      "targets": {
+        "language": "python",
+        "frameworks": [
+          "claude-agent-sdk"
+        ],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-python-generic",
+      "version": "1.0.0",
+      "summary": "General Moda SDK integration for a Python app when no specific framework or provider skill matches.",
+      "targets": {
+        "language": "python",
+        "frameworks": [],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-python-langchain",
+      "version": "1.0.0",
+      "summary": "Instrument a Python LangChain or LangGraph app with Moda: init before the framework, explicit conversation ids around every run.",
+      "targets": {
+        "language": "python",
+        "frameworks": [
+          "langchain"
+        ],
+        "providers": []
+      }
+    },
+    {
+      "id": "integration-python-openai",
+      "version": "1.0.0",
+      "summary": "Auto-instrument openai client calls with Moda in a Python app; no per-call changes required.",
+      "targets": {
+        "language": "python",
+        "frameworks": [],
+        "providers": [
+          "openai"
+        ]
+      }
+    }
+  ]
+}

package/skills/integration/integration-node-anthropic/EXAMPLE.md

@@ -0,0 +1,59 @@
+# Golden reference: Express + Anthropic SDK + Moda
+
+The complete finished integration for a minimal Express chat server that
+calls the Anthropic SDK directly. Match this structure; adapt names to the
+target repository.
+
+## src/server.ts
+
+```typescript
+import express from 'express';
+import { Moda, withContext } from 'moda-ai';
+import Anthropic from '@anthropic-ai/sdk';
+
+// Initialize Moda once, before the Anthropic client is created. After this,
+// every messages.create / messages.stream call is captured automatically.
+await Moda.init(process.env.MODA_API_KEY!);
+
+const client = new Anthropic();
+const app = express();
+app.use(express.json());
+
+app.post('/chat', async (req, res) => {
+  const { sessionId, userId, message } = req.body;
+
+  // Scoped context: safe under concurrent requests.
+  const response = await withContext(`session_${sessionId}`, userId, async () =>
+    client.messages.create({
+      model: 'claude-sonnet-4-20250514',
+      max_tokens: 1024,
+      messages: [{ role: 'user', content: message }],
+    }),
+  );
+
+  const reply = response.content
+    .filter((block) => block.type === 'text')
+    .map((block) => block.text)
+    .join('');
+  res.json({ reply });
+});
+
+// Flush pending telemetry on shutdown.
+process.on('SIGTERM', async () => {
+  await Moda.flush();
+  await Moda.shutdown();
+  process.exit(0);
+});
+
+app.listen(3000);
+```
+
+## What changed, and what did not
+
+- `moda-ai` added to `package.json` dependencies.
+- One `Moda.init` call added at startup, before `new Anthropic()`.
+- The handler wraps its existing Anthropic call in `withContext`; the
+  `messages.create` call itself is unchanged — instrumentation is automatic.
+- A `SIGTERM` handler flushes telemetry on shutdown.
+- No `.env` file was created or edited; `MODA_API_KEY` is read from the
+  runtime environment.

package/skills/integration/integration-node-anthropic/SKILL.md

@@ -0,0 +1,150 @@
+---
+id: integration-node-anthropic
+name: "Integrate Moda with the Anthropic SDK (Node.js / TypeScript)"
+version: 1.0.0
+category: integration
+targets:
+  language: node
+  frameworks: []
+  providers:
+    - anthropic
+sdk_package: moda-ai
+summary: "Auto-instrument @anthropic-ai/sdk client calls with Moda in a Node.js or TypeScript app; no per-call changes required."
+---
+
+# Integrate Moda with the Anthropic SDK (Node.js / TypeScript)
+
+Follow the steps below in order. Each step has a stop condition; when you hit
+one, stop and report instead of guessing. `EXAMPLE.md` in this directory shows
+the complete finished integration; match its structure. For API details beyond
+this skill, read https://docs.moda.dev/ingestion/providers/anthropic and
+https://docs.moda.dev/ingestion/moda-sdk-node (if the installed `moda-ai`
+package ships docs under `node_modules/moda-ai/docs/`, prefer those; they
+match the installed SDK version).
+
+## Safety rules (apply to every step)
+
+- Only touch the repository you were launched in.
+- Never write the `MODA_API_KEY` value (or any secret) into source files, and
+  never create or edit `.env` files. The key belongs in the runtime
+  environment or a secret manager.
+- Make the smallest correct change. Match the existing code style and imports.
+- Do not commit unless the user asks.
+- If a step is ambiguous in this repository, stop and report rather than
+  guessing.
+
+## Step 1: Confirm the raw Anthropic client is the integration surface
+
+Find the real LLM call sites: `client.messages.create(...)` or
+`client.messages.stream(...)` on a client constructed with `new Anthropic()`
+from the `@anthropic-ai/sdk` package.
+
+- If the Anthropic calls go through a wrapper framework instead — the `ai`
+  package (Vercel AI SDK) or LangChain — stop: instrument the wrapper layer
+  with its dedicated skill, never the underlying provider client.
+- If the repo wraps its Anthropic client in a helper module (for example
+  `lib/anthropic.ts` exporting a shared client), plan to instrument at that
+  one place; do not edit every call site.
+- If there are no Anthropic call sites at all, stop and report.
+
+## Step 2: Install the SDK
+
+Install `moda-ai` with the package manager this repository already uses
+(check the lockfile: `bun.lock`/`bun.lockb` means bun, `pnpm-lock.yaml` means
+pnpm, `yarn.lock` means yarn, otherwise npm):
+
+```bash
+npm install moda-ai
+```
+
+If `moda-ai` is already in `package.json`, skip the install.
+
+## Step 3: Initialize Moda once at startup, before the client is created
+
+Instrumentation is automatic: once `Moda.init` has run, every
+`messages.create` / `messages.stream` call (including extended thinking and
+tool use) is captured with no per-call changes.
+
+`Moda.init` must run before the Anthropic client is constructed. If a
+`Moda.init` call already exists, verify it runs at startup before client
+creation and skip this step; never add a second call.
+
+```typescript
+import { Moda } from 'moda-ai';
+import Anthropic from '@anthropic-ai/sdk';
+
+await Moda.init(process.env.MODA_API_KEY!);
+
+const client = new Anthropic();
+```
+
+If the client lives in a shared helper module, initialize Moda at the top of
+the application entry point (before that module is imported), or at the top
+of the helper module itself — whichever the existing structure makes
+smallest.
+
+## Step 4: Set conversation and user context
+
+Set a stable conversation id before each LLM call so multi-turn
+conversations group together, and a user id when one user can be identified.
+
+For sequential code, use the global properties:
+
+```typescript
+Moda.conversationId = `session_${sessionId}`;
+Moda.userId = userId;
+```
+
+For concurrent request handlers (any web server), use the scoped helper so
+overlapping requests do not leak context into each other:
+
+```typescript
+import { withContext } from 'moda-ai';
+
+const response = await withContext(`session_${sessionId}`, userId, async () =>
+  client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: userMessage }],
+  }),
+);
+```
+
+Reuse the session/thread identifier the app already has. If no session
+identifier exists anywhere, the SDK falls back to hashing the first user
+message plus the system prompt — acceptable only for simple chatbots that
+pass full message history on every call. If this repo is an agent framework
+or does not pass full history, an explicit conversation id is required; stop
+and report if you cannot find a session identifier to use.
+
+## Step 5: Flush before exit
+
+For short-lived scripts and CLIs, flush before the process exits:
+
+```typescript
+await Moda.flush();
+```
+
+For long-running servers, flush on shutdown:
+
+```typescript
+process.on('SIGTERM', async () => {
+  await Moda.flush();
+  await Moda.shutdown();
+  process.exit(0);
+});
+```
+
+## Step 6: Validate
+
+Report the packages installed, files edited, and any step a human still needs
+to do (for example setting `MODA_API_KEY` in the deploy environment). Then
+verify telemetry reaches Moda:
+
+```bash
+moda doctor --online --json
+```
+
+The report should show recent traces. If it does not, confirm `MODA_API_KEY`
+is available in the runtime environment and that `Moda.init()` runs before
+the Anthropic client is created.