@moda-ai/cli 1.11.0 → 1.12.0

package/dist/init/sdk-guide.d.ts

@@ -14,8 +14,35 @@ export type SdkGuideContext = {
     packageManagers: string[];
     runtimeSummary: RuntimeSummary;
 };
+/**
+ * Write the human/agent-readable fallback guide (.moda/SDK_INTEGRATION.md).
+ *
+ * When a bundled integration skill matches the detected stack, the guide is
+ * rendered from that skill's content plus the detection block (one shared
+ * renderer with the agent-prompt path). When no skill resolves (no language
+ * detected) the slim generic guide is used; when a skill resolved but its
+ * content could not be loaded (missing/unreadable bundle) the generic guide is
+ * flagged as a degraded fallback and pinned to the detected stack.
+ */
 export declare function writeSdkIntegrationGuide(cwd?: string): string;
+/** Shared renderer: detection block + the resolved skill's full content. */
+export declare function renderSkillBasedGuide(skillId: string, skillMd: string, context: SdkGuideContext): string;
+/** The "What Moda Detected" section, shared by prompts and guides. */
+export declare function renderDetectionBlock(context: SdkGuideContext): string;
+/** Drop a SKILL.md's YAML frontmatter so only the prose body is rendered. */
+export declare function stripSkillFrontmatter(markdown: string): string;
 export declare function detectSdkGuideContext(cwd: string): SdkGuideContext;
-export declare function renderSdkIntegrationGuide(context: SdkGuideContext): string;
+/**
+ * Slim last-resort guide, used when no bundled skill resolves (no language
+ * detected) or when a skill resolved but its content could not be loaded (the
+ * bundle is missing/unreadable). Detected stacks with readable content get the
+ * far richer skill-based guide via renderSkillBasedGuide().
+ *
+ * When `resolvedSkillId` is set the intro flags the degradation and pins the
+ * reader to the detection block instead of claiming no stack was detected —
+ * mirrors the degraded fallback in the agent-prompt path so a successful
+ * detection never reads as stack-less.
+ */
+export declare function renderSdkIntegrationGuide(context: SdkGuideContext, resolvedSkillId?: string): string;
 export {};
 //# sourceMappingURL=sdk-guide.d.ts.map

package/dist/init/sdk-guide.js

@@ -1,13 +1,73 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { readBundledSkillMd } from '../skills-bundled.js';
+import { resolveIntegrationSkillId } from './skill-resolver.js';
 export const SDK_GUIDE_PATH = '.moda/SDK_INTEGRATION.md';
+/**
+ * Write the human/agent-readable fallback guide (.moda/SDK_INTEGRATION.md).
+ *
+ * When a bundled integration skill matches the detected stack, the guide is
+ * rendered from that skill's content plus the detection block (one shared
+ * renderer with the agent-prompt path). When no skill resolves (no language
+ * detected) the slim generic guide is used; when a skill resolved but its
+ * content could not be loaded (missing/unreadable bundle) the generic guide is
+ * flagged as a degraded fallback and pinned to the detected stack.
+ */
 export function writeSdkIntegrationGuide(cwd = process.cwd()) {
     const relativePath = SDK_GUIDE_PATH;
     const absolutePath = join(cwd, relativePath);
+    const context = detectSdkGuideContext(cwd);
+    const skillId = resolveIntegrationSkillId(context);
+    const skillMd = skillId ? readBundledSkillMd(skillId) : null;
+    const content = skillId && skillMd
+        ? renderSkillBasedGuide(skillId, skillMd, context)
+        : renderSdkIntegrationGuide(context, skillId ?? undefined);
     mkdirSync(dirname(absolutePath), { recursive: true });
-    writeFileSync(absolutePath, renderSdkIntegrationGuide(detectSdkGuideContext(cwd)));
+    writeFileSync(absolutePath, content);
     return relativePath;
 }
+/** Shared renderer: detection block + the resolved skill's full content. */
+export function renderSkillBasedGuide(skillId, skillMd, context) {
+    return [
+        '# Moda SDK Integration Guide',
+        '',
+        `Generated by \`moda init\` from the bundled integration skill \`${skillId}\`.`,
+        'If this project has the skill materialized at',
+        `\`.claude/skills/${skillId}/SKILL.md\`, prefer reading it there (EXAMPLE.md`,
+        'beside it shows the finished integration).',
+        '',
+        renderDetectionBlock(context),
+        '',
+        '---',
+        '',
+        stripSkillFrontmatter(skillMd).trim(),
+        '',
+    ].join('\n');
+}
+/** The "What Moda Detected" section, shared by prompts and guides. */
+export function renderDetectionBlock(context) {
+    const languages = context.languages.length > 0 ? context.languages.join(', ') : 'Not detected yet';
+    const packageManagers = context.packageManagers.length > 0 ? context.packageManagers.join(', ') : 'Not detected yet';
+    const providers = context.providerHints.length > 0 ? context.providerHints.join(', ') : 'No provider imports detected yet';
+    const frameworks = context.frameworkHints.length > 0 ? context.frameworkHints.join(', ') : 'No agent framework detected yet';
+    const runtimeNames = context.runtimeSummary.runtimeAgentNames.slice(0, 8);
+    return [
+        '## What Moda Detected',
+        '',
+        `- Languages: ${languages}`,
+        `- Package managers: ${packageManagers}`,
+        ...(context.installCommands.length > 0 ? [`- Install command(s): ${context.installCommands.join(' | ')}`] : []),
+        `- Model providers: ${providers}`,
+        `- Agent frameworks: ${frameworks}`,
+        `- Harness graph: ${context.runtimeSummary.runtimeAgents} runtime agent(s), ${context.runtimeSummary.agentFamilies} agent family/families`,
+        ...(runtimeNames.length > 0 ? [`- Runtime agents: ${runtimeNames.join(', ')}`] : []),
+    ].join('\n');
+}
+const GUIDE_FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
+/** Drop a SKILL.md's YAML frontmatter so only the prose body is rendered. */
+export function stripSkillFrontmatter(markdown) {
+    return markdown.replace(GUIDE_FRONTMATTER_RE, '');
+}
 export function detectSdkGuideContext(cwd) {
     const languages = [];
     const installCommands = [];
@@ -64,41 +124,51 @@ export function detectSdkGuideContext(cwd) {
         runtimeSummary,
     };
 }
-export function renderSdkIntegrationGuide(context) {
-    const languages = context.languages.length > 0 ? context.languages.join(', ') : 'Not detected yet';
-    const packageManagers = context.packageManagers.length > 0 ? context.packageManagers.join(', ') : 'Not detected yet';
+/**
+ * Slim last-resort guide, used when no bundled skill resolves (no language
+ * detected) or when a skill resolved but its content could not be loaded (the
+ * bundle is missing/unreadable). Detected stacks with readable content get the
+ * far richer skill-based guide via renderSkillBasedGuide().
+ *
+ * When `resolvedSkillId` is set the intro flags the degradation and pins the
+ * reader to the detection block instead of claiming no stack was detected —
+ * mirrors the degraded fallback in the agent-prompt path so a successful
+ * detection never reads as stack-less.
+ */
+export function renderSdkIntegrationGuide(context, resolvedSkillId) {
     const installCommands = context.installCommands.length > 0
         ? context.installCommands
         : ['npm install moda-ai', 'pip install moda-ai'];
-    const providers = context.providerHints.length > 0 ? context.providerHints.join(', ') : 'No provider imports detected yet';
-    const frameworks = context.frameworkHints.length > 0 ? context.frameworkHints.join(', ') : 'No agent framework detected yet';
-    const runtimeNames = context.runtimeSummary.runtimeAgentNames.slice(0, 8);
+    const intro = resolvedSkillId
+        ? [
+            `Generated by \`moda init\`. This repo's stack resolved to the bundled integration skill`,
+            `\`${resolvedSkillId}\`, but its content could not be loaded (the skill bundle is missing`,
+            'or unreadable in this install), so this is the general checklist. Tailor every step to',
+            'the stack in "What Moda Detected" below rather than treating this as a repo with no',
+            'detected stack.',
+        ]
+        : [
+            'Generated by `moda init`. No specific stack was detected, so this is the',
+            'general checklist; the full per-framework references live at',
+            'https://docs.moda.dev/ingestion.',
+        ];
     return `${[
         '# Moda SDK Integration Guide',
         '',
-        'Generated by `moda init`.',
+        ...intro,
         '',
-        'V1 does not install packages or edit source code automatically. Use this guide as the human-approved checklist for SDK package installation and code instrumentation.',
-        '',
-        '## What Moda Detected',
-        '',
-        `- Languages: ${languages}`,
-        `- Package managers: ${packageManagers}`,
-        `- Model providers: ${providers}`,
-        `- Agent frameworks: ${frameworks}`,
-        `- Harness graph: ${context.runtimeSummary.runtimeAgents} runtime agent(s), ${context.runtimeSummary.agentFamilies} agent family/families`,
-        ...(runtimeNames.length > 0 ? [`- Runtime agents: ${runtimeNames.join(', ')}`] : []),
+        renderDetectionBlock(context),
         '',
-        '## 1. Approve Package Installation',
+        '## 1. Install The SDK',
         '',
-        'Run the command that matches the harness you are instrumenting:',
+        'Use the package manager this repo already uses:',
         '',
         ...installCommands.flatMap((command) => ['```bash', command, '```', '']),
-        'Do not paste `MODA_API_KEY` into source. Keep it in your deployment environment, secret manager, or local shell.',
+        'Do not paste `MODA_API_KEY` into source or `.env` files. Keep it in your deployment environment, secret manager, or local shell.',
         '',
         '## 2. Initialize Moda Once At Startup',
         '',
-        'Initialize before any OpenAI, Anthropic, LangChain, AutoGen, CrewAI, or app-specific LLM client is created.',
+        'Initialize before any LLM client is created.',
         '',
         'Node.js / TypeScript:',
         '',
@@ -111,14 +181,16 @@ export function renderSdkIntegrationGuide(context) {
         'Python:',
         '',
         '```python',
+        'import os',
+        '',
         'import moda',
         '',
-        'moda.init()  # reads MODA_API_KEY',
+        'moda.init(os.environ["MODA_API_KEY"])',
         '```',
         '',
         '## 3. Set Conversation And User Context',
         '',
-        'Set a stable conversation id before each LLM call. If one user can reach the same agent through SMS, WhatsApp, voice, or Slack, use the same user id across channels.',
+        'Set a stable conversation id before each LLM call, and a user id when one user can be identified. For concurrent request handlers, use the scoped context helpers from the SDK instead of setting global context across overlapping requests.',
         '',
         'Node.js / TypeScript:',
         '',
@@ -134,87 +206,17 @@ export function renderSdkIntegrationGuide(context) {
         'moda.user_id = user_id',
         '```',
         '',
-        'For concurrent request handlers, use the scoped context helpers from the SDK instead of setting global context across overlapping requests.',
+        '## 4. Flush Before Exit',
         '',
-        '## 4. Attribute Managed Prompts',
+        'Node.js / TypeScript: `await Moda.flush();` — Python: `moda.flush()`.',
         '',
-        'Keep prompts in files, sync them with Moda, and render them through the SDK so production traces point at exact prompt versions.',
-        '',
-        '```bash',
-        'moda prompts status',
-        'moda prompts sync',
-        '```',
-        '',
-        'Node.js / TypeScript:',
-        '',
-        '```ts',
-        'const rendered = Moda.prompt("support.triage").render({',
-        '  ticket: { text: userMessage },',
-        '});',
-        '',
-        'await client.chat.completions.create({',
-        '  model: "gpt-4o",',
-        '  messages: rendered.messages,',
-        '});',
-        '```',
-        '',
-        'Python:',
-        '',
-        '```python',
-        'rendered = moda.prompt("support.triage").render({',
-        '    "ticket": {"text": user_message},',
-        '})',
-        '',
-        'client.chat.completions.create(',
-        '    model="gpt-4o",',
-        '    messages=rendered["messages"],',
-        ')',
-        '```',
-        '',
-        '## 5. Vercel AI SDK',
-        '',
-        'If this project uses the `ai` package or `@ai-sdk/*`, pass Moda telemetry explicitly:',
-        '',
-        '```ts',
-        'const result = await generateText({',
-        "  model: openai('gpt-4o'),",
-        '  messages: rendered.messages,',
-        '  experimental_telemetry: Moda.getVercelAITelemetry(),',
-        '});',
-        '```',
-        '',
-        'Render the prompt before calling `Moda.getVercelAITelemetry()` so prompt metadata is attached.',
-        '',
-        '## 6. Flush Before Exit',
-        '',
-        'Node.js / TypeScript:',
-        '',
-        '```ts',
-        'await Moda.flush();',
-        '```',
-        '',
-        'Python:',
-        '',
-        '```python',
-        'moda.flush()',
-        '```',
-        '',
-        '## 7. Validate',
-        '',
-        'After the code change is reviewed and merged, run:',
+        '## 5. Validate',
         '',
         '```bash',
         'moda doctor --online --json',
         '```',
         '',
-        'The check should show recent traces/logs/runs. If it does not, confirm `MODA_API_KEY` is available at runtime and that `Moda.init()` runs before the first LLM client is created.',
-        '',
-        '## Human Approval Boundary',
-        '',
-        '- This guide is safe for `moda init` to write automatically.',
-        '- Package installation is a human-approved step.',
-        '- Source edits are a human-approved step.',
-        '- Environment variable files are not created or updated by `moda init`.',
+        'The check should show recent traces/logs/runs. If it does not, confirm `MODA_API_KEY` is available at runtime and that Moda initialization runs before the first LLM client is created.',
         '',
     ].join('\n')}`;
 }
@@ -293,6 +295,8 @@ function addPythonHints(text, providers, frameworks) {
         providers.add('Anthropic');
     if (/\blangchain\b|\blanggraph\b/.test(lower))
         frameworks.add('LangChain / LangGraph');
+    if (/claude[-_]agent[-_]sdk/.test(lower))
+        frameworks.add('Claude Agent SDK');
     if (/\bcrewai\b/.test(lower))
         frameworks.add('CrewAI');
     if (/\bautogen\b/.test(lower))

package/dist/init/sdk-integration.d.ts

@@ -1,7 +1,9 @@
 import { type CodingAgentAdapter } from '../harness.js';
+import { type SdkGuideContext } from './sdk-guide.js';
 export type SdkIntegrationResult = {
     status: 'integrated';
     adapter: CodingAgentAdapter;
+    skillId?: string;
 } | {
     status: 'no-agent';
 } | {
@@ -18,9 +20,27 @@ export interface SdkIntegrationOptions {
     onProgress?: (message: string) => void;
 }
 /**
- * Pick an installed coding-agent CLI and run it, in write mode, to integrate the
- * Moda SDK into the repo. Returns `no-agent` (without throwing) when no CLI is
- * installed so the caller can fall back to writing the static guide.
+ * Pick an installed coding-agent CLI and run it, in write mode, to integrate
+ * the Moda SDK into the repo. Returns `no-agent` (without throwing) when no
+ * CLI is installed so the caller can fall back to writing the static guide.
  */
 export declare function runSdkIntegration(options?: SdkIntegrationOptions): Promise<SdkIntegrationResult>;
+/** How the resolved integration skill (if any) reaches the agent prompt. */
+export interface SdkIntegrationPromptSkill {
+    /** Skill materialized to `.claude/skills/<id>/` — point the agent at it. */
+    installedSkillId?: string;
+    /** Resolved skill we could read but not materialize — inline its content. */
+    inlineSkill?: {
+        skillId: string;
+        markdown: string;
+    };
+    /**
+     * The skill the detected stack resolved to, if any. Set even when neither
+     * install nor inline succeeded (e.g. the bundle is entirely absent) so the
+     * generic fallback can flag the degradation and tell the agent to tailor the
+     * checklist to the detected stack instead of treating it as stack-less.
+     */
+    resolvedSkillId?: string;
+}
+export declare function renderSdkIntegrationPrompt(context: SdkGuideContext, skill?: SdkIntegrationPromptSkill): string;
 //# sourceMappingURL=sdk-integration.d.ts.map

package/dist/init/sdk-integration.js

@@ -2,14 +2,20 @@
 // Moda SDK directly, instead of leaving a guide for the user to action by hand.
 //
 // This reuses the same coding-agent spawn machinery as `moda harness analyze`
-// (see src/harness.ts), but in write mode: the agent is expected to install the
-// SDK package and edit source to instrument LLM calls.
+// (see src/harness.ts), but in write mode. The integration knowledge itself
+// lives in the bundled integration skills (skills/integration/, authored in
+// packages/integration-skills/): we resolve the skill matching the detected
+// stack, materialize it into .claude/skills/<id>/, and hand the agent a thin
+// prompt that points at the skill file — the prompt no longer inlines API
+// documentation.
 import { codingAgentDisplayName, detectAvailableCodingAgents, runCodingAgent, } from '../harness.js';
-import { detectSdkGuideContext, renderSdkIntegrationGuide } from './sdk-guide.js';
+import { installIntegrationSkill, readBundledSkillMd } from '../skills-bundled.js';
+import { detectSdkGuideContext, renderDetectionBlock, renderSdkIntegrationGuide, stripSkillFrontmatter, } from './sdk-guide.js';
+import { resolveIntegrationSkillId } from './skill-resolver.js';
 /**
- * Pick an installed coding-agent CLI and run it, in write mode, to integrate the
- * Moda SDK into the repo. Returns `no-agent` (without throwing) when no CLI is
- * installed so the caller can fall back to writing the static guide.
+ * Pick an installed coding-agent CLI and run it, in write mode, to integrate
+ * the Moda SDK into the repo. Returns `no-agent` (without throwing) when no
+ * CLI is installed so the caller can fall back to writing the static guide.
  */
 export async function runSdkIntegration(options = {}) {
     const cwd = options.cwd ?? process.cwd();
@@ -19,13 +25,46 @@ export async function runSdkIntegration(options = {}) {
     const adapter = options.adapter && available.some((item) => item.adapter === options.adapter)
         ? options.adapter
         : available[0].adapter;
-    const prompt = renderSdkIntegrationPrompt(cwd);
     const human = options.human ?? false;
     const emit = (message) => {
         options.onProgress?.(message);
         if (human)
             process.stderr.write(`  ${codingAgentDisplayName(adapter)}: ${message}\n`);
     };
+    const context = detectSdkGuideContext(cwd);
+    const skillId = resolveIntegrationSkillId(context);
+    let installedSkillId;
+    let inlineSkill;
+    if (skillId) {
+        try {
+            const install = installIntegrationSkill(skillId, cwd);
+            installedSkillId = install.skillId;
+            emit(install.status === 'installed'
+                ? `Installed integration skill ${skillId} to .claude/skills/${skillId}/`
+                : `Integration skill ${skillId} already up to date`);
+        }
+        catch (err) {
+            // Materialization failed (unwritable .claude/skills target, a colliding
+            // user-authored file, or a missing/corrupt bundle). Do NOT silently drop
+            // the resolved stack to the generic checklist — that would contradict the
+            // detection block. When the bundle is still readable, inline the skill's
+            // content into the prompt so the agent keeps the stack-specific steps;
+            // only a truly absent bundle (e.g. an unbuilt dev tree) falls through to
+            // the generic guide.
+            const message = err instanceof Error ? err.message : String(err);
+            emit(`Could not materialize integration skill ${skillId}: ${message}`);
+            const skillMd = readBundledSkillMd(skillId);
+            if (skillMd) {
+                inlineSkill = { skillId, markdown: skillMd };
+                emit(`Inlining ${skillId} instructions into the agent prompt instead`);
+            }
+        }
+    }
+    const prompt = renderSdkIntegrationPrompt(context, {
+        installedSkillId,
+        inlineSkill,
+        resolvedSkillId: skillId ?? undefined,
+    });
     const run = await runCodingAgent({
         adapter,
         prompt,
@@ -49,32 +88,75 @@ export async function runSdkIntegration(options = {}) {
             detail: `${codingAgentDisplayName(adapter)} exited with status ${run.status ?? 'unknown'}.${tail ? `\n${tail}` : ''}`,
         };
     }
-    return { status: 'integrated', adapter };
+    return { status: 'integrated', adapter, skillId: installedSkillId };
 }
-function renderSdkIntegrationPrompt(cwd) {
-    const guide = renderSdkIntegrationGuide(detectSdkGuideContext(cwd));
-    return [
+const SAFETY_RULES = [
+    'Scope and safety rules:',
+    '- Only touch this repository (the working directory you were launched in).',
+    '- Install the Moda SDK with the package manager this repo already uses.',
+    '- Instrument the real LLM call sites; do not invent files or frameworks that are not here.',
+    '- Never write MODA_API_KEY (or any secret) into source files, and never create or edit',
+    '  .env files. The key belongs in the environment / a secret manager at runtime.',
+    '- Make the smallest correct change. Match the existing code style and imports.',
+    '- If something is ambiguous or the repo has no LLM calls to instrument, stop and explain',
+    '  rather than guessing.',
+];
+export function renderSdkIntegrationPrompt(context, skill = {}) {
+    const header = [
         'You are running inside `moda init` as a one-shot SDK integration task. The user has',
         'approved letting you install packages and edit source files in THIS repository to add',
         'Moda LLM observability. Do the integration now — do not just describe it.',
         '',
-        'Scope and safety rules:',
-        '- Only touch this repository (the working directory you were launched in).',
-        '- Install the Moda SDK with the package manager this repo already uses.',
-        '- Instrument the real LLM call sites; do not invent files or frameworks that are not here.',
-        '- Never write MODA_API_KEY (or any secret) into source files, and never create or edit',
-        '  .env files. The key belongs in the environment / a secret manager at runtime.',
-        '- Make the smallest correct change. Match the existing code style and imports.',
-        '- If something is ambiguous or the repo has no LLM calls to instrument, stop and explain',
-        '  rather than guessing.',
+        ...SAFETY_RULES,
         '',
-        'Follow this Moda-authored integration spec exactly (it reflects the detected languages,',
-        'package managers, providers, and frameworks for this repo):',
+        renderDetectionBlock(context),
         '',
-        guide,
+    ];
+    const body = renderPromptBody(context, skill);
+    const footer = [
         '',
         'When finished, print a short summary of: the package(s) installed, the files you edited,',
         'and any step a human still needs to do (e.g. setting MODA_API_KEY in the deploy env).',
-    ].join('\n');
+    ];
+    return [...header, ...body, ...footer].join('\n');
+}
+/**
+ * Four-tier body, most-specific first:
+ *   1. skill materialized on disk → point the agent at it;
+ *   2. skill resolved but not materialized → inline its content so a detected
+ *      stack never degrades to the generic checklist;
+ *   3. skill resolved but its content is unavailable (bundle absent/unreadable)
+ *      → generic checklist, but flagged as a degraded fallback and pinned to the
+ *      detected stack so it is not silently treated as stack-less;
+ *   4. nothing resolved (no language detected) → plain generic checklist.
+ */
+function renderPromptBody(context, skill) {
+    if (skill.installedSkillId) {
+        const id = skill.installedSkillId;
+        return [
+            `Read \`.claude/skills/${id}/SKILL.md\` and follow its steps exactly, including its`,
+            `stop conditions. \`EXAMPLE.md\` in the same directory shows the finished integration —`,
+            'match its structure.',
+        ];
+    }
+    if (skill.inlineSkill) {
+        return [
+            `The bundled integration skill \`${skill.inlineSkill.skillId}\` matches this repo's stack,`,
+            'but could not be written to disk, so its full content is inlined below. Follow its steps',
+            'exactly, including its stop conditions:',
+            '',
+            '---',
+            '',
+            stripSkillFrontmatter(skill.inlineSkill.markdown).trim(),
+        ];
+    }
+    // Tiers 3 & 4 share one renderer: renderSdkIntegrationGuide flags the degraded
+    // fallback (and pins to the detection block) when a skill resolved but its
+    // content was unavailable, and renders the plain generic checklist otherwise.
+    return [
+        'Follow this Moda-authored integration checklist:',
+        '',
+        renderSdkIntegrationGuide(context, skill.resolvedSkillId),
+    ];
 }
 //# sourceMappingURL=sdk-integration.js.map

package/dist/init/skill-resolver.d.ts

@@ -0,0 +1,19 @@
+import type { SdkGuideContext } from './sdk-guide.js';
+type Language = 'node' | 'python';
+type Framework = 'vercel-ai-sdk' | 'langchain' | 'claude-agent-sdk';
+type Provider = 'openai' | 'anthropic';
+interface ResolutionRow {
+    language: Language;
+    framework?: Framework;
+    provider?: Provider;
+    skillId: string;
+}
+/** The §2.3 resolution table, encoded as data. Order matters. */
+export declare const RESOLUTION_TABLE: readonly ResolutionRow[];
+/**
+ * Resolve the detected context to a bundled skill id, or null when no
+ * language was detected (callers fall back to the slim generic guide).
+ */
+export declare function resolveIntegrationSkillId(context: SdkGuideContext): string | null;
+export {};
+//# sourceMappingURL=skill-resolver.d.ts.map

package/dist/init/skill-resolver.js

@@ -0,0 +1,78 @@
+// src/init/skill-resolver.ts — deterministic resolution from detected project
+// context to a bundled integration-skill id.
+//
+// Pure function, zero LLM involvement. The table is ordered; the first
+// matching row wins. Wrapper frameworks beat raw providers: if the Vercel AI
+// SDK or LangChain is present, the wrapper layer gets instrumented, never the
+// underlying openai/anthropic client.
+/** The §2.3 resolution table, encoded as data. Order matters. */
+export const RESOLUTION_TABLE = [
+    { language: 'node', framework: 'vercel-ai-sdk', skillId: 'integration-node-vercel-ai-sdk' },
+    { language: 'node', framework: 'langchain', skillId: 'integration-node-langchain' },
+    { language: 'python', framework: 'langchain', skillId: 'integration-python-langchain' },
+    { language: 'python', framework: 'claude-agent-sdk', skillId: 'integration-python-claude-agent-sdk' },
+    { language: 'node', provider: 'openai', skillId: 'integration-node-openai' },
+    { language: 'node', provider: 'anthropic', skillId: 'integration-node-anthropic' },
+    { language: 'python', provider: 'openai', skillId: 'integration-python-openai' },
+    { language: 'python', provider: 'anthropic', skillId: 'integration-python-anthropic' },
+    { language: 'node', skillId: 'integration-node-generic' },
+    { language: 'python', skillId: 'integration-python-generic' },
+];
+/**
+ * Resolve the detected context to a bundled skill id, or null when no
+ * language was detected (callers fall back to the slim generic guide).
+ */
+export function resolveIntegrationSkillId(context) {
+    const languages = normalizeLanguages(context.languages);
+    const frameworks = normalizeFrameworks(context.frameworkHints);
+    const providers = normalizeProviders(context.providerHints);
+    for (const row of RESOLUTION_TABLE) {
+        if (!languages.has(row.language))
+            continue;
+        if (row.framework && !frameworks.has(row.framework))
+            continue;
+        if (row.provider && !providers.has(row.provider))
+            continue;
+        return row.skillId;
+    }
+    return null;
+}
+function normalizeLanguages(languages) {
+    const result = new Set();
+    for (const language of languages) {
+        const lower = language.toLowerCase();
+        if (lower.includes('node') || lower.includes('typescript') || lower.includes('javascript')) {
+            result.add('node');
+        }
+        if (lower.includes('python'))
+            result.add('python');
+    }
+    return result;
+}
+function normalizeFrameworks(frameworkHints) {
+    const result = new Set();
+    for (const hint of frameworkHints) {
+        const lower = hint.toLowerCase();
+        if (lower.includes('vercel ai sdk') || lower.includes('vercel-ai-sdk') || lower.includes('ai sdk')) {
+            result.add('vercel-ai-sdk');
+        }
+        if (lower.includes('langchain') || lower.includes('langgraph'))
+            result.add('langchain');
+        if (lower.includes('claude agent sdk') || lower.includes('claude-agent-sdk')) {
+            result.add('claude-agent-sdk');
+        }
+    }
+    return result;
+}
+function normalizeProviders(providerHints) {
+    const result = new Set();
+    for (const hint of providerHints) {
+        const lower = hint.toLowerCase();
+        if (lower.includes('openai'))
+            result.add('openai');
+        if (lower.includes('anthropic'))
+            result.add('anthropic');
+    }
+    return result;
+}
+//# sourceMappingURL=skill-resolver.js.map

package/dist/skills-bundled.d.ts

@@ -0,0 +1,35 @@
+export interface BundledSkillIndexEntry {
+    id: string;
+    version: string;
+    summary: string;
+    targets: {
+        language: string;
+        frameworks: string[];
+        providers: string[];
+    };
+}
+export interface BundledSkillIndex {
+    schema_version: string;
+    bundled_at: string;
+    cli_version: string;
+    skills: BundledSkillIndexEntry[];
+}
+export interface IntegrationSkillInstallResult {
+    skillId: string;
+    status: 'installed' | 'unchanged';
+    paths: string[];
+}
+/** Directory holding the bundled skills (overridable for tests). */
+export declare function bundledSkillsDir(): string;
+/** Read the bundled skill menu, or null when no bundle is present. */
+export declare function readBundledIndex(): BundledSkillIndex | null;
+/** Read a bundled skill's SKILL.md, or null when it is not bundled. */
+export declare function readBundledSkillMd(skillId: string): string | null;
+/**
+ * Materialize a bundled integration skill into the project.
+ *
+ * Idempotent: unchanged files are left untouched, and a second install with
+ * identical content reports status 'unchanged' without writing.
+ */
+export declare function installIntegrationSkill(skillId: string, cwd?: string): IntegrationSkillInstallResult;
+//# sourceMappingURL=skills-bundled.d.ts.map