@orchid-labs/pluxx 0.1.0 → 0.1.1

package/src/cli/init-from-mcp.ts

@@ -2,7 +2,13 @@ import { existsSync } from 'fs'
 import { mkdir } from 'fs/promises'
 import { basename, resolve } from 'path'
 import type { HookEntry, McpServer, PluginConfig, TargetPlatform, UserConfigEntry } from '../schema'
-import type { IntrospectedMcpServer, IntrospectedMcpTool } from '../mcp/introspect'
+import type {
+  IntrospectedMcpPrompt,
+  IntrospectedMcpResource,
+  IntrospectedMcpResourceTemplate,
+  IntrospectedMcpServer,
+  IntrospectedMcpTool,
+} from '../mcp/introspect'
 import { collectUserConfigEntries } from '../user-config'
 
 export interface McpScaffoldOptions {
@@ -47,6 +53,10 @@ interface PlannedSkill {
   title: string
   description: string
   tools: IntrospectedMcpTool[]
+  resources: IntrospectedMcpResource[]
+  resourceTemplates: IntrospectedMcpResourceTemplate[]
+  prompts: IntrospectedMcpPrompt[]
+  workflowKey?: string | null
 }
 
 export interface PersistedSkill {
@@ -102,6 +112,7 @@ export interface McpScaffoldMetadata {
   settings: {
     pluginName: string
     displayName: string
+    description?: string
     skillGrouping: McpSkillGrouping
     requestedHookMode: McpHookMode
     generatedHookMode: McpHookMode
@@ -110,11 +121,17 @@ export interface McpScaffoldMetadata {
   }
   userConfig: UserConfigEntry[]
   tools: IntrospectedMcpTool[]
+  resources?: IntrospectedMcpResource[]
+  resourceTemplates?: IntrospectedMcpResourceTemplate[]
+  prompts?: IntrospectedMcpPrompt[]
   skills: Array<{
     dirName: string
     title: string
     description?: string
     toolNames: string[]
+    resourceUris?: string[]
+    resourceTemplateUris?: string[]
+    promptNames?: string[]
   }>
   managedFiles: string[]
 }
@@ -277,25 +294,35 @@ export async function applyMcpScaffoldPlan(rootDir: string, plan: McpScaffoldPla
 export async function planMcpScaffold(options: McpScaffoldOptions): Promise<McpScaffoldPlan> {
   const pluginName = toKebabCase(options.pluginName) || 'mcp-plugin'
   const displayName = options.displayName
-    ?? options.introspection.serverInfo.title
-    ?? humanizeName(pluginName)
+    ?? deriveDisplayName(options.introspection, pluginName)
+  const plannedSkills = planSkillScaffoldsFromPersisted(
+    options.introspection.tools,
+    options.skillGrouping,
+    options.introspection.resources ?? [],
+    options.introspection.resourceTemplates ?? [],
+    options.introspection.prompts ?? [],
+    options.persistedSkills,
+    options.toolRenames,
+  )
   const description = options.description
-    ?? options.introspection.serverInfo.description
-    ?? `Generated from the ${displayName} MCP server.`
+    ?? deriveScaffoldDescription({
+      displayName,
+      introspection: options.introspection,
+      plannedSkills,
+    })
   const serverName = options.serverName
     ?? toKebabCase(options.introspection.serverInfo.name)
     ?? pluginName
-  const runtimeAuthMode = options.runtimeAuthMode ?? 'inline'
+  const runtimeAuthMode = options.runtimeAuthMode
+    ?? (
+      options.source.transport !== 'stdio' && options.source.auth?.type === 'platform'
+        ? 'platform'
+        : 'inline'
+    )
 
   const instructionsPath = resolve(options.rootDir, 'INSTRUCTIONS.md')
   const skillRoot = resolve(options.rootDir, 'skills')
   const commandsRoot = resolve(options.rootDir, 'commands')
-  const plannedSkills = planSkillScaffoldsFromPersisted(
-    options.introspection.tools,
-    options.skillGrouping,
-    options.persistedSkills,
-    options.toolRenames,
-  )
   const userConfigSource = {
     targets: options.targets,
     mcp: {
@@ -356,6 +383,9 @@ export async function planMcpScaffold(options: McpScaffoldOptions): Promise<McpS
           instructions: options.introspection.instructions,
           skills: plannedSkills,
           tools: options.introspection.tools,
+          resources: options.introspection.resources ?? [],
+          resourceTemplates: options.introspection.resourceTemplates ?? [],
+          prompts: options.introspection.prompts ?? [],
           userConfig,
         }),
       existsSync(instructionsPath) ? await Bun.file(instructionsPath).text() : undefined,
@@ -572,6 +602,31 @@ export function buildSkillContent(skill: PlannedSkill): string {
     }
   }
 
+  if (skill.resources.length > 0 || skill.resourceTemplates.length > 0) {
+    lines.push('## Related Resources', '')
+
+    for (const resource of skill.resources) {
+      const label = resource.name ?? resource.title ?? resource.uri
+      lines.push(`- \`${label}\`: ${summarizeResourceForInstructions(resource)}`)
+    }
+
+    for (const template of skill.resourceTemplates) {
+      lines.push(`- \`${template.name}\`: ${summarizeResourceTemplateForInstructions(template)}`)
+    }
+
+    lines.push('')
+  }
+
+  if (skill.prompts.length > 0) {
+    lines.push('## Related Prompt Templates', '')
+
+    for (const prompt of skill.prompts) {
+      lines.push(`- \`${prompt.name}\`: ${summarizePromptForInstructions(prompt)}`)
+    }
+
+    lines.push('')
+  }
+
   lines.push(
     '## Example Requests',
     '',
@@ -597,25 +652,59 @@ export function buildSkillContent(skill: PlannedSkill): string {
 export function buildCommandContent(skill: PlannedSkill, existingContent?: string): string {
   const description = truncate(cleanSingleLineText(skill.description), 140)
   const argumentHint = inferCommandArgumentHint(skill)
+  const entryBlurb = buildCommandEntryBlurb(skill)
+  const hasRelatedResources = skill.resources.length > 0 || skill.resourceTemplates.length > 0
+  const hasRelatedPrompts = skill.prompts.length > 0
+  const workflowSteps = [
+    '1. Interpret `$ARGUMENTS` as the user request for this workflow.',
+    '2. Choose the most specific tool in this surface.',
+  ]
+
+  if (hasRelatedResources) {
+    workflowSteps.push(`${workflowSteps.length + 1}. Use related MCP resources or resource templates as canonical context when they fit the request.`)
+  }
+
+  if (hasRelatedPrompts) {
+    workflowSteps.push(`${workflowSteps.length + 1}. Use related MCP prompt templates when they provide a canonical starting point for the task.`)
+  }
+
+  workflowSteps.push(`${workflowSteps.length + 1}. Ask for missing required inputs only if the request does not already provide them.`)
+  workflowSteps.push(`${workflowSteps.length + 1}. Return a concise task-focused answer instead of raw JSON unless the user asks for it.`)
+
   const generatedContent = [
     '---',
     `description: ${JSON.stringify(description)}`,
     `argument-hint: ${JSON.stringify(argumentHint)}`,
     '---',
     '',
-    `Use the ${skill.title.toLowerCase()} workflow for this plugin.`,
+    entryBlurb,
     '',
     'Arguments: $ARGUMENTS',
     '',
     'Primary tools:',
     ...skill.tools.map((tool) => `- \`${tool.name}\``),
+    ...(hasRelatedResources
+      ? [
+          '',
+          'Related resources:',
+          ...skill.resources.map((resource) => {
+            const label = resource.name ?? resource.title ?? resource.uri
+            return `- \`${label}\``
+          }),
+          ...skill.resourceTemplates.map((template) => `- \`${template.name}\``),
+        ]
+      : []),
+    ...(hasRelatedPrompts
+      ? [
+          '',
+          'Related prompt templates:',
+          ...skill.prompts.map((prompt) => `- \`${prompt.name}\``),
+        ]
+      : []),
     '',
     'Workflow:',
     '',
-    '1. Interpret `$ARGUMENTS` as the user request for this workflow.',
-    '2. Choose the most specific tool in this surface.',
-    '3. Ask for missing required inputs only if the request does not already provide them.',
-    '4. Return a concise task-focused answer instead of raw JSON unless the user asks for it.',
+    ...workflowSteps,
   ].join('\n')
 
   return wrapManagedMarkdown(
@@ -636,6 +725,9 @@ export function buildInstructionsContent(input: {
   instructions?: string
   skills: PlannedSkill[]
   tools: IntrospectedMcpTool[]
+  resources: IntrospectedMcpResource[]
+  resourceTemplates: IntrospectedMcpResourceTemplate[]
+  prompts: IntrospectedMcpPrompt[]
   userConfig?: UserConfigEntry[]
 }): string {
   const accessLine = describePluginAccess(input.displayName, input.source, input.runtimeAuthMode ?? 'inline')
@@ -664,11 +756,33 @@ export function buildInstructionsContent(input: {
     lines.push(`- \`${tool.name}\`: ${summarizeToolForInstructions(tool)}`)
   }
 
+  if (input.resources.length > 0 || input.resourceTemplates.length > 0) {
+    lines.push('', '## Resource Surfaces', '')
+
+    for (const resource of input.resources.slice(0, 8)) {
+      const label = resource.name ?? resource.title ?? resource.uri
+      lines.push(`- \`${label}\`: ${summarizeResourceForInstructions(resource)}`)
+    }
+
+    for (const template of input.resourceTemplates.slice(0, 8)) {
+      lines.push(`- \`${template.name}\`: ${summarizeResourceTemplateForInstructions(template)}`)
+    }
+  }
+
+  if (input.prompts.length > 0) {
+    lines.push('', '## Prompt Templates', '')
+
+    for (const prompt of input.prompts.slice(0, 8)) {
+      lines.push(`- \`${prompt.name}\`: ${summarizePromptForInstructions(prompt)}`)
+    }
+  }
+
   lines.push(
     '',
     '## Operating Notes',
     '',
     '- Prefer the most specific tool that matches the user request.',
+    '- If the MCP exposes resources or prompt templates, use them as canonical context before improvising your own workflow.',
     '- Confirm required inputs before calling a tool.',
     '- Summarize returned data instead of dumping raw JSON unless the user asks for it.',
   )
@@ -715,8 +829,10 @@ export function buildConfigTemplate(input: {
 }): string {
   const targets = input.targets.map((target) => JSON.stringify(target)).join(', ')
   const mcpBlock = buildMcpBlock(input.serverName, input.source)
+  const shortDescription = truncate(firstSentenceOf(cleanSingleLineText(input.description)), 140)
   const brandFields = [
     `displayName: ${JSON.stringify(input.displayName)}`,
+    shortDescription ? `shortDescription: ${JSON.stringify(shortDescription)}` : null,
     input.websiteUrl ? `websiteURL: ${JSON.stringify(input.websiteUrl)}` : null,
   ].filter(Boolean).join(',\n    ')
   const userConfigBlock = input.userConfig && input.userConfig.length > 0
@@ -984,6 +1100,11 @@ function buildMcpScaffoldMetadata(input: {
     settings: {
       pluginName: input.pluginName,
       displayName: input.displayName,
+      description: deriveScaffoldDescription({
+        displayName: input.displayName,
+        introspection: input.introspection,
+        plannedSkills: input.plannedSkills,
+      }),
       skillGrouping: input.skillGrouping,
       requestedHookMode: input.requestedHookMode,
       generatedHookMode: input.generatedHookMode,
@@ -992,11 +1113,17 @@ function buildMcpScaffoldMetadata(input: {
     },
     userConfig: input.userConfig,
     tools: input.introspection.tools,
+    resources: input.introspection.resources ?? [],
+    resourceTemplates: input.introspection.resourceTemplates ?? [],
+    prompts: input.introspection.prompts ?? [],
     skills: input.plannedSkills.map((skill) => ({
       dirName: skill.dirName,
       title: skill.title,
       description: skill.description,
       toolNames: skill.tools.map((tool) => tool.name),
+      resourceUris: skill.resources.map((resource) => resource.uri),
+      resourceTemplateUris: skill.resourceTemplates.map((resource) => resource.uriTemplate),
+      promptNames: skill.prompts.map((prompt) => prompt.name),
     })),
     managedFiles: input.managedFiles,
   }
@@ -1005,17 +1132,29 @@ function buildMcpScaffoldMetadata(input: {
 export function planSkillScaffolds(
   tools: IntrospectedMcpTool[],
   grouping: McpSkillGrouping = 'workflow',
+  resources: IntrospectedMcpResource[] = [],
+  resourceTemplates: IntrospectedMcpResourceTemplate[] = [],
+  prompts: IntrospectedMcpPrompt[] = [],
 ): PlannedSkill[] {
   if (grouping === 'tool') {
     return allocateSkillDirectoryNames(
-      tools
-        .sort((a, b) => a.name.localeCompare(b.name))
-        .map((tool) => ({
-          dirName: toKebabCase(tool.name) || 'tool',
-          title: tool.title ?? humanizeName(tool.name),
-          description: tool.description ?? `Use the \`${tool.name}\` MCP tool for this workflow.`,
-          tools: [tool],
-        })),
+      attachRelatedSurfaceSignals(
+        tools
+          .sort((a, b) => a.name.localeCompare(b.name))
+          .map((tool) => ({
+            dirName: toKebabCase(tool.name) || 'tool',
+            title: tool.title ?? humanizeName(tool.name),
+            description: tool.description ?? `Use the \`${tool.name}\` MCP tool for this workflow.`,
+            tools: [tool],
+            resources: [],
+            resourceTemplates: [],
+            prompts: [],
+            workflowKey: classifyToolWorkflow(tool),
+          })),
+        resources,
+        resourceTemplates,
+        prompts,
+      ),
     )
   }
 
@@ -1045,6 +1184,10 @@ export function planSkillScaffolds(
       title: definition.title,
       description: definition.description,
       tools: bucket.sort((a, b) => a.name.localeCompare(b.name)),
+      resources: [],
+      resourceTemplates: [],
+      prompts: [],
+      workflowKey: definition.key,
     })
   }
 
@@ -1054,20 +1197,29 @@ export function planSkillScaffolds(
       title: tool.title ?? humanizeName(tool.name),
       description: tool.description ?? `Use the \`${tool.name}\` MCP tool for this workflow.`,
       tools: [tool],
+      resources: [],
+      resourceTemplates: [],
+      prompts: [],
+      workflowKey: classifyToolWorkflow(tool),
     })
   }
 
-  return allocateSkillDirectoryNames(plannedSkills)
+  return allocateSkillDirectoryNames(
+    attachRelatedSurfaceSignals(plannedSkills, resources, resourceTemplates, prompts),
+  )
 }
 
 function planSkillScaffoldsFromPersisted(
   tools: IntrospectedMcpTool[],
   grouping: McpSkillGrouping = 'workflow',
+  resources: IntrospectedMcpResource[] = [],
+  resourceTemplates: IntrospectedMcpResourceTemplate[] = [],
+  prompts: IntrospectedMcpPrompt[] = [],
   persistedSkills: PersistedSkill[] = [],
   toolRenames: Map<string, string> = new Map(),
 ): PlannedSkill[] {
   if (persistedSkills.length === 0) {
-    return planSkillScaffolds(tools, grouping)
+    return planSkillScaffolds(tools, grouping, resources, resourceTemplates, prompts)
   }
 
   const toolByName = new Map(tools.map((tool) => [tool.name, tool]))
@@ -1092,15 +1244,21 @@ function planSkillScaffoldsFromPersisted(
       title: skill.title,
       description: skill.description ?? `Handle ${skill.title.toLowerCase()} workflows.`,
       tools: matchedTools,
+      resources: [],
+      resourceTemplates: [],
+      prompts: [],
+      workflowKey: inferWorkflowKeyFromTools(matchedTools),
     })
   }
 
   const remainingTools = tools.filter((tool) => !assigned.has(tool.name))
   if (remainingTools.length > 0) {
-    planned.push(...planSkillScaffolds(remainingTools, grouping))
+    planned.push(...planSkillScaffolds(remainingTools, grouping, resources, resourceTemplates, prompts))
   }
 
-  return allocateSkillDirectoryNames(planned)
+  return allocateSkillDirectoryNames(
+    attachRelatedSurfaceSignals(planned, resources, resourceTemplates, prompts),
+  )
 }
 
 function buildPersistedTaxonomy(skills: PlannedSkill[]): PersistedSkill[] {
@@ -1216,12 +1374,45 @@ function allocateSkillDirectoryNames(skills: PlannedSkill[]): PlannedSkill[] {
 }
 
 function classifyToolWorkflow(tool: IntrospectedMcpTool): string | null {
+  return classifyWorkflowSurface(
+    [
+      normalizeIdentifier(tool.name).toLowerCase(),
+      normalizeIdentifier(tool.title ?? '').toLowerCase(),
+    ].join(' '),
+    (tool.description ?? '').toLowerCase(),
+  )
+}
+
+function classifyResourceWorkflow(resource: IntrospectedMcpResource): string | null {
   const primaryText = [
-    normalizeIdentifier(tool.name).toLowerCase(),
-    normalizeIdentifier(tool.title ?? '').toLowerCase(),
+    normalizeIdentifier(resource.name ?? '').toLowerCase(),
+    normalizeIdentifier(resource.title ?? '').toLowerCase(),
+    normalizeIdentifier(resource.uri).toLowerCase(),
   ].join(' ')
-  const secondaryText = (tool.description ?? '').toLowerCase()
+  const secondaryText = (resource.description ?? '').toLowerCase()
+  return classifyWorkflowSurface(primaryText, secondaryText)
+}
 
+function classifyResourceTemplateWorkflow(template: IntrospectedMcpResourceTemplate): string | null {
+  const primaryText = [
+    normalizeIdentifier(template.name).toLowerCase(),
+    normalizeIdentifier(template.title ?? '').toLowerCase(),
+    normalizeIdentifier(template.uriTemplate).toLowerCase(),
+  ].join(' ')
+  const secondaryText = (template.description ?? '').toLowerCase()
+  return classifyWorkflowSurface(primaryText, secondaryText)
+}
+
+function classifyPromptWorkflow(prompt: IntrospectedMcpPrompt): string | null {
+  const primaryText = [
+    normalizeIdentifier(prompt.name).toLowerCase(),
+    ...(prompt.arguments ?? []).map((argument) => normalizeIdentifier(argument.name).toLowerCase()),
+  ].join(' ')
+  const secondaryText = (prompt.description ?? '').toLowerCase()
+  return classifyWorkflowSurface(primaryText, secondaryText)
+}
+
+function classifyWorkflowSurface(primaryText: string, secondaryText: string): string | null {
   let bestMatch: string | null = null
   let bestScore = 0
 
@@ -1246,6 +1437,61 @@ function classifyToolWorkflow(tool: IntrospectedMcpTool): string | null {
   return bestMatch
 }
 
+function inferWorkflowKeyFromTools(tools: IntrospectedMcpTool[]): string | null {
+  for (const tool of tools) {
+    const workflowKey = classifyToolWorkflow(tool)
+    if (workflowKey) return workflowKey
+  }
+  return null
+}
+
+function attachRelatedSurfaceSignals(
+  skills: PlannedSkill[],
+  resources: IntrospectedMcpResource[],
+  resourceTemplates: IntrospectedMcpResourceTemplate[],
+  prompts: IntrospectedMcpPrompt[],
+): PlannedSkill[] {
+  const nextSkills = skills.map((skill) => ({
+    ...skill,
+    resources: [...skill.resources],
+    resourceTemplates: [...skill.resourceTemplates],
+    prompts: [...skill.prompts],
+  }))
+
+  const attachResource = (workflowKey: string | null, apply: (skill: PlannedSkill) => void) => {
+    if (!workflowKey) return
+    const target = nextSkills.find((skill) => skill.workflowKey === workflowKey)
+    if (!target) return
+    apply(target)
+  }
+
+  for (const resource of resources) {
+    attachResource(classifyResourceWorkflow(resource), (skill) => {
+      if (!skill.resources.some((entry) => entry.uri === resource.uri)) {
+        skill.resources.push(resource)
+      }
+    })
+  }
+
+  for (const template of resourceTemplates) {
+    attachResource(classifyResourceTemplateWorkflow(template), (skill) => {
+      if (!skill.resourceTemplates.some((entry) => entry.uriTemplate === template.uriTemplate)) {
+        skill.resourceTemplates.push(template)
+      }
+    })
+  }
+
+  for (const prompt of prompts) {
+    attachResource(classifyPromptWorkflow(prompt), (skill) => {
+      if (!skill.prompts.some((entry) => entry.name === prompt.name)) {
+        skill.prompts.push(prompt)
+      }
+    })
+  }
+
+  return nextSkills
+}
+
 function buildSkillFrontmatterDescription(skill: PlannedSkill): string {
   if (skill.tools.length === 1) {
     const tool = skill.tools[0]
@@ -1263,7 +1509,18 @@ function buildSkillFrontmatterDescription(skill: PlannedSkill): string {
 function buildInstructionSkillSummary(skill: PlannedSkill): string {
   const toolNames = skill.tools.map((tool) => `\`${tool.name}\``).join(', ')
   const description = truncate(cleanSingleLineText(skill.description), 180)
-  return `\`${skill.dirName}\`: ${description} Primary tools: ${toolNames}.`
+  const resourceLabels = [
+    ...skill.resources.map((resource) => `\`${resource.name ?? resource.title ?? resource.uri}\``),
+    ...skill.resourceTemplates.map((template) => `\`${template.name}\``),
+  ]
+  const promptLabels = skill.prompts.map((prompt) => `\`${prompt.name}\``)
+  const resourceNote = resourceLabels.length > 0
+    ? ` Related resources: ${resourceLabels.join(', ')}.`
+    : ''
+  const promptNote = promptLabels.length > 0
+    ? ` Related prompt templates: ${promptLabels.join(', ')}.`
+    : ''
+  return `\`${skill.dirName}\`: ${description} Primary tools: ${toolNames}.${resourceNote}${promptNote}`
 }
 
 function inferCommandArgumentHint(skill: PlannedSkill): string {
@@ -1289,6 +1546,58 @@ function inferCommandArgumentHint(skill: PlannedSkill): string {
   return [...fieldHints].slice(0, 2).map((hint) => `[${hint}]`).join(' ')
 }
 
+function buildCommandEntryBlurb(skill: PlannedSkill): string {
+  const intent = inferSkillIntentPhrase(skill)
+  const resourceLabels = [
+    ...skill.resources.map((resource) => resource.name ?? resource.title ?? resource.uri),
+    ...skill.resourceTemplates.map((template) => template.name),
+  ]
+  const promptLabels = skill.prompts.map((prompt) => prompt.name)
+  const resourceNote = resourceLabels.length > 0
+    ? ` Check related MCP resources such as ${resourceLabels.slice(0, 2).map((label) => `\`${label}\``).join(' and ')} when they fit the request.`
+    : ''
+  const promptNote = promptLabels.length > 0
+    ? ` Prompt templates such as ${promptLabels.slice(0, 2).map((label) => `\`${label}\``).join(' and ')} can provide a canonical starting point.`
+    : ''
+  return `Use this command when the user asks to ${intent}.${resourceNote}${promptNote}`
+}
+
+function inferSkillIntentPhrase(skill: PlannedSkill): string {
+  const toolDescription = skill.tools.length === 1
+    ? firstSentenceOf(cleanSingleLineText(skill.tools[0].description))
+    : ''
+  const fallback = firstSentenceOf(cleanSingleLineText(skill.description))
+  const cleaned = normalizeSkillIntentPhrase(toolDescription || fallback)
+
+  if (!cleaned) {
+    return `work with ${skill.title.toLowerCase()} in this plugin`
+  }
+
+  return startsWithActionVerb(cleaned) ? cleaned : `work on ${cleaned}`
+}
+
+function normalizeSkillIntentPhrase(value: string): string {
+  if (!value) return ''
+
+  const withoutGenericPrefixes = value
+    .replace(/^use (?:the |this )?(?:workflow|command|tool)\s+(?:for|to)\s+/i, '')
+    .replace(/^use the `[^`]+` mcp tool for this workflow\.?/i, '')
+    .replace(/^handle\s+/i, '')
+    .replace(/^this (?:workflow|command|tool)\s+/i, '')
+    .replace(/\s+for this plugin\.?$/i, '')
+    .replace(/\s+for this workflow\.?$/i, '')
+    .trim()
+
+  if (!withoutGenericPrefixes) return ''
+
+  const normalized = withoutGenericPrefixes.charAt(0).toLowerCase() + withoutGenericPrefixes.slice(1)
+  return normalized.replace(/[.?!]+$/, '').trim()
+}
+
+function startsWithActionVerb(value: string): boolean {
+  return /^(search|find|look up|get|fetch|create|update|delete|list|query|send|check|compare|build|run|research)\b/i.test(value)
+}
+
 function mapSchemaFieldToArgumentHint(fieldName: string): string {
   const value = fieldName.toLowerCase()
 
@@ -1325,6 +1634,46 @@ function summarizeToolForInstructions(tool: IntrospectedMcpTool): string {
   return truncate(parts.join(' '), 240)
 }
 
+function summarizeResourceForInstructions(resource: IntrospectedMcpResource): string {
+  const descriptor = firstSentenceOf(cleanSingleLineText(resource.description ?? ''))
+  const location = resource.uri ? `URI: \`${resource.uri}\`.` : ''
+  const mimeType = resource.mimeType ? ` Format: ${resource.mimeType}.` : ''
+  const parts = [
+    descriptor || 'Reference resource exposed by the MCP.',
+    location,
+    mimeType,
+  ].filter(Boolean)
+
+  return truncate(parts.join(' '), 240)
+}
+
+function summarizeResourceTemplateForInstructions(template: IntrospectedMcpResourceTemplate): string {
+  const descriptor = firstSentenceOf(cleanSingleLineText(template.description ?? ''))
+  const uriTemplate = template.uriTemplate ? `URI template: \`${template.uriTemplate}\`.` : ''
+  const mimeType = template.mimeType ? ` Format: ${template.mimeType}.` : ''
+  const parts = [
+    descriptor || 'Parameterized MCP resource template.',
+    uriTemplate,
+    mimeType,
+  ].filter(Boolean)
+
+  return truncate(parts.join(' '), 240)
+}
+
+function summarizePromptForInstructions(prompt: IntrospectedMcpPrompt): string {
+  const descriptor = firstSentenceOf(cleanSingleLineText(prompt.description ?? ''))
+  const args = prompt.arguments?.slice(0, 4).map((argument) => {
+    const required = argument.required ? 'required' : 'optional'
+    return `\`${argument.name}\` (${required})`
+  }) ?? []
+  const parts = [
+    descriptor || 'Prompt template exposed by the MCP.',
+    args.length > 0 ? `Arguments: ${args.join(', ')}.` : '',
+  ].filter(Boolean)
+
+  return truncate(parts.join(' '), 240)
+}
+
 function summarizeServerGuidance(value: string): string[] {
   const lines = value
     .split('\n')
@@ -1391,10 +1740,7 @@ export function buildToolExampleRequest(tool: IntrospectedMcpTool): string {
   const action = inferToolAction(tool)
   const objectLabel = inferToolObject(tool)
   const context = buildToolRequestContext(tool)
-
-  const sentence = context
-    ? `${action} ${objectLabel} ${context}.`
-    : `${action} ${objectLabel}.`
+  const sentence = buildExampleSentence(action, objectLabel, context)
 
   return sentence.charAt(0).toUpperCase() + sentence.slice(1)
 }
@@ -1409,14 +1755,25 @@ function inferToolAction(tool: IntrospectedMcpTool): string {
   if (/^(list)\b/.test(identifier)) return 'list'
   if (/^(query)\b/.test(identifier)) return 'query'
   if (/^(search)\b/.test(identifier)) return 'search'
+  if (/^(send|post|publish)\b/.test(identifier)) return 'send'
   return 'find'
 }
 
 function inferToolObject(tool: IntrospectedMcpTool): string {
   const raw = normalizeIdentifier(tool.title ?? tool.name).trim()
   const stripped = raw.replace(/^(find|get|fetch|lookup|look up|search|list|create|add|update|edit|delete|remove|query)\s+/i, '')
-  const candidate = stripped || raw
-  return candidate ? candidate.toLowerCase() : 'results'
+  const tokens = (stripped || raw).toLowerCase().split(/\s+/).filter(Boolean)
+
+  while (tokens.length > 1 && SECONDARY_ACTION_TOKENS.has(tokens[0])) {
+    tokens.shift()
+  }
+
+  while (tokens.length > 1 && NOISE_OBJECT_TOKENS.has(tokens[tokens.length - 1])) {
+    tokens.pop()
+  }
+
+  const candidate = tokens.join(' ').trim()
+  return candidate || 'results'
 }
 
 function buildToolRequestContext(tool: IntrospectedMcpTool): string {
@@ -1451,6 +1808,75 @@ function buildToolRequestContext(tool: IntrospectedMcpTool): string {
   return `with ${placeholder}`
 }
 
+const SECONDARY_ACTION_TOKENS = new Set([
+  'find',
+  'get',
+  'fetch',
+  'lookup',
+  'search',
+  'list',
+  'create',
+  'add',
+  'update',
+  'edit',
+  'delete',
+  'remove',
+  'query',
+  'send',
+  'post',
+  'publish',
+])
+
+const NOISE_OBJECT_TOKENS = new Set(['tool', 'workflow', 'mcp'])
+
+function buildExampleSentence(action: string, objectLabel: string, context: string): string {
+  const objectPhrase = buildObjectPhrase(action, objectLabel)
+  const withContext = context ? `${objectPhrase} ${context}` : objectPhrase
+  return `${withContext}.`
+}
+
+function buildObjectPhrase(action: string, objectLabel: string): string {
+  const trimmed = objectLabel.trim() || 'results'
+  const pluralized = maybePluralizePhrase(trimmed)
+
+  if (action === 'create') return `create a new ${trimmed}`
+  if (action === 'update') return `update ${withArticle(trimmed)}`
+  if (action === 'delete') return `delete the ${trimmed}`
+  if (action === 'look up') return `look up ${withArticle(trimmed)}`
+  if (action === 'list') return `list ${pluralized}`
+  if (action === 'find' || action === 'search' || action === 'query') return `${action} ${pluralized}`
+  if (action === 'send') return `send ${withArticle(trimmed)}`
+  return `${action} ${trimmed}`
+}
+
+function withArticle(value: string): string {
+  if (!value) return 'results'
+  if (/^(a|an|the)\b/i.test(value)) return value
+  if (/\b(and|or)\b/i.test(value) || value.endsWith('s')) return value
+  const firstWord = value.split(/\s+/)[0].toLowerCase()
+  const article = /^[aeiou]/.test(firstWord) ? 'an' : 'a'
+  return `${article} ${value}`
+}
+
+function maybePluralizePhrase(value: string): string {
+  const words = value.trim().split(/\s+/).filter(Boolean)
+  if (words.length === 0) return 'results'
+
+  const last = words[words.length - 1]
+  if (/s$/i.test(last) || /people$/i.test(last)) return value
+  if (/y$/i.test(last) && !/[aeiou]y$/i.test(last)) {
+    words[words.length - 1] = `${last.slice(0, -1)}ies`
+    return words.join(' ')
+  }
+  if (/(ch|sh|x|z)$/i.test(last)) {
+    words[words.length - 1] = `${last}es`
+    return words.join(' ')
+  }
+
+  words[words.length - 1] = `${last}s`
+  return words.join(' ')
+}
+
 function formatSchemaType(value: unknown): string {
   if (typeof value === 'string') return value
   if (Array.isArray(value)) {
@@ -1474,7 +1900,10 @@ function describePluginAccess(displayName: string, source: McpServer, runtimeAut
 
 function describeAuthRequirement(source: McpServer, runtimeAuthMode: McpRuntimeAuthMode = 'inline'): string {
   if (runtimeAuthMode === 'platform' && source.transport !== 'stdio') {
-    return 'Claude Code and Cursor use platform-managed auth at runtime (for example native OAuth/custom connector flows). Exported env vars remain useful for scaffold refreshes and other non-platform-managed targets.'
+    if (source.auth?.type === 'platform') {
+      return 'This server relies on platform-managed OAuth at runtime. Pluxx does not complete interactive OAuth in the CLI; use the host-native auth flow before calling authenticated tools.'
+    }
+    return 'Claude Code and Cursor use platform-managed auth at runtime (for example native OAuth/custom connector flows). Exported env vars remain useful for scaffold refreshes and other non-platform-managed targets like Codex and OpenCode.'
   }
 
   if (!source.auth || source.auth.type === 'none') {
@@ -1482,7 +1911,7 @@ function describeAuthRequirement(source: McpServer, runtimeAuthMode: McpRuntimeA
   }
 
   if (source.auth.type === 'platform') {
-    return 'Use the platform-managed auth flow before calling authenticated tools.'
+    return 'This server relies on platform-managed OAuth at runtime. Pluxx does not complete interactive OAuth in the CLI; use the host-native auth flow before calling authenticated tools.'
   }
 
   if (source.auth.type === 'header') {
@@ -1609,3 +2038,78 @@ export function derivePluginName(introspection: IntrospectedMcpServer, source: M
 
   return 'mcp-plugin'
 }
+
+export function deriveDisplayName(introspection: IntrospectedMcpServer, pluginName: string): string {
+  const candidates = [
+    introspection.serverInfo.title,
+    introspection.serverInfo.name,
+    pluginName,
+  ].filter((value): value is string => typeof value === 'string' && value.trim().length > 0)
+
+  for (const candidate of candidates) {
+    const polished = polishDisplayName(candidate)
+    if (polished) return polished
+  }
+
+  return 'MCP Plugin'
+}
+
+function polishDisplayName(value: string): string {
+  const raw = value.trim()
+  if (!raw) return ''
+
+  const looksMachineIdentifier = /^[a-z0-9._/-]+$/.test(raw) || /[-_/]/.test(raw) || raw === raw.toLowerCase()
+  let candidate = looksMachineIdentifier ? humanizeName(raw) : raw
+
+  candidate = candidate
+    .replace(/\bmcp\b/gi, 'MCP')
+    .replace(/\bMCP\s+Server\b/gi, 'MCP')
+    .replace(/\s+/g, ' ')
+    .trim()
+
+  return candidate
+}
+
+function deriveScaffoldDescription(input: {
+  displayName: string
+  introspection: IntrospectedMcpServer
+  plannedSkills: PlannedSkill[]
+}): string {
+  const serverDescription = truncate(cleanSingleLineText(input.introspection.serverInfo.description), 200)
+  if (serverDescription && !isGenericServerDescription(serverDescription)) {
+    return serverDescription
+  }
+
+  const skillTitles = [...new Set(
+    input.plannedSkills
+      .map((skill) => cleanSingleLineText(skill.title).toLowerCase())
+      .filter(Boolean),
+  )].slice(0, 2)
+
+  if (skillTitles.length === 1) {
+    return `${input.displayName} plugin scaffold for ${skillTitles[0]} workflows.`
+  }
+
+  if (skillTitles.length === 2) {
+    return `${input.displayName} plugin scaffold for ${skillTitles[0]} and ${skillTitles[1]} workflows.`
+  }
+
+  const toolCount = input.introspection.tools.length
+  if (toolCount > 0) {
+    return `${input.displayName} plugin scaffold for ${toolCount} MCP tool${toolCount === 1 ? '' : 's'}.`
+  }
+
+  return `${input.displayName} plugin scaffold for MCP-driven workflows.`
+}
+
+function isGenericServerDescription(value: string): boolean {
+  const normalized = value.toLowerCase().trim()
+  if (!normalized) return true
+
+  if (normalized.startsWith('generated from ')) return true
+  if (normalized === 'mcp server') return true
+  if (normalized === 'an mcp server') return true
+  if (normalized === 'a mcp server') return true
+
+  return false
+}