@soederpop/luca 0.0.6 → 0.0.8

package/src/commands/describe.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import { commands } from '../command.js'
 import { CommandOptionsSchema } from '../schemas/base.js'
 import type { ContainerContext } from '../container.js'
-import type { IntrospectionSection } from '../introspection/index.js'
+import type { IntrospectionSection, MethodIntrospection, GetterIntrospection } from '../introspection/index.js'
 
 declare module '../command.js' {
 	interface AvailableCommands {
@@ -10,7 +10,7 @@ declare module '../command.js' {
 	}
 }
 
-const REGISTRY_NAMES = ['features', 'clients', 'servers', 'commands', 'endpoints'] as const
+const REGISTRY_NAMES = ['features', 'clients', 'servers', 'commands', 'endpoints', 'selectors'] as const
 type RegistryName = (typeof REGISTRY_NAMES)[number]
 
 /** Maps flag names to the section they represent. 'description' is handled specially. */
@@ -67,6 +67,7 @@ type ResolvedTarget =
 	| { kind: 'container' }
 	| { kind: 'registry'; name: RegistryName }
 	| { kind: 'helper'; registry: RegistryName; id: string }
+	| { kind: 'member'; registry: RegistryName; id: string; member: string; memberType: 'method' | 'getter' }
 
 class DescribeError extends Error {
 	constructor(message: string) {
@@ -75,6 +76,24 @@ class DescribeError extends Error {
 	}
 }
 
+/**
+ * Extract a short summary from a potentially long description string.
+ * Takes text up to the first markdown heading, bullet list, or code block,
+ * capped at ~300 chars on a sentence boundary.
+ */
+function extractSummary(description: string): string {
+	// Strip from the first markdown heading/bullet/code block onward
+	const cut = description.search(/\s\*\*[A-Z][\w\s]+:\*\*|```|^\s*[-*]\s/m)
+	const text = cut > 0 ? description.slice(0, cut).trim() : description
+
+	if (text.length <= 300) return text
+
+	// Truncate on sentence boundary
+	const sentenceEnd = text.lastIndexOf('. ', 300)
+	if (sentenceEnd > 100) return text.slice(0, sentenceEnd + 1)
+	return text.slice(0, 300).trim() + '...'
+}
+
 /**
  * Normalize an identifier to a comparable form by stripping file extensions,
  * converting kebab-case and snake_case to lowercase-no-separators.
@@ -99,9 +118,44 @@ function fuzzyFind(registry: any, input: string): string | undefined {
 	return (registry.available as string[]).find((id: string) => normalize(id) === norm)
 }
 
+/**
+ * Try to resolve "helperName.memberName" by searching all registries for the helper,
+ * then checking if memberName is a method or getter on it.
+ * Returns a 'member' target or null if no match.
+ */
+function resolveHelperMember(helperName: string, memberName: string, container: any): ResolvedTarget | null {
+	for (const registryName of REGISTRY_NAMES) {
+		const reg = container[registryName]
+		if (!reg) continue
+		const found = fuzzyFind(reg, helperName)
+		if (!found) continue
+
+		const Ctor = reg.lookup(found)
+		const introspection = Ctor.introspect?.()
+		if (!introspection) continue
+
+		if (introspection.methods?.[memberName]) {
+			return { kind: 'member', registry: registryName, id: found, member: memberName, memberType: 'method' }
+		}
+		if (introspection.getters?.[memberName]) {
+			return { kind: 'member', registry: registryName, id: found, member: memberName, memberType: 'getter' }
+		}
+
+		// If we found the helper but not the member, give a helpful error
+		const allMembers = [
+			...Object.keys(introspection.methods || {}).map((m: string) => m + '()'),
+			...Object.keys(introspection.getters || {}),
+		].sort()
+		throw new DescribeError(
+			`"${memberName}" is not a known method or getter on ${found}.\n\nAvailable members:\n  ${allMembers.join(', ')}`
+		)
+	}
+	return null
+}
+
 /**
  * Parse a single target string into a resolved target.
- * Accepts: "container", "features", "features.fs", "fs", etc.
+ * Accepts: "container", "features", "features.fs", "fs", "ui.banner", etc.
  */
 function resolveTarget(target: string, container: any): ResolvedTarget {
 	const lower = target.toLowerCase()
@@ -135,6 +189,12 @@ function resolveTarget(target: string, container: any): ResolvedTarget {
 			}
 			return { kind: 'helper', registry, id: resolved }
 		}
+
+		// Not a registry prefix — try "helper.member" (e.g. "ui.banner", "fs.readFile")
+		const helperName = prefix!
+		const memberName = rest.join('.')
+		const memberResult = resolveHelperMember(helperName, memberName, container)
+		if (memberResult) return memberResult
 	}
 
 	// Unqualified name: search all registries (fuzzy)
@@ -319,6 +379,77 @@ function getContainerData(container: any, sections: (IntrospectionSection | 'des
 	}
 }
 
+/**
+ * Walk the prototype chain of a base class to collect shared methods and getters.
+ * These are the methods/getters inherited by all helpers in a registry.
+ */
+function collectSharedMembers(baseClass: any): { methods: string[]; getters: string[] } {
+	const methods: string[] = []
+	const getters: string[] = []
+
+	let proto = baseClass?.prototype
+	while (proto && proto.constructor.name !== 'Object') {
+		for (const k of Object.getOwnPropertyNames(proto)) {
+			if (k === 'constructor' || k.startsWith('_')) continue
+			const desc = Object.getOwnPropertyDescriptor(proto, k)
+			if (!desc) continue
+			if (desc.get && !getters.includes(k)) getters.push(k)
+			else if (typeof desc.value === 'function' && !methods.includes(k)) methods.push(k)
+		}
+		proto = Object.getPrototypeOf(proto)
+	}
+
+	return { methods: methods.sort(), getters: getters.sort() }
+}
+
+/**
+ * Find the intermediate parent class between a helper constructor and the registry's
+ * base class (e.g. RestClient between ElevenLabsClient and Client).
+ * Returns the intermediate class constructor, or null if the helper extends the base directly.
+ */
+function findIntermediateParent(Ctor: any, baseClass: any): { name: string; methods: string[]; getters: string[] } | null {
+	if (!baseClass) return null
+
+	// Walk up from Ctor's parent to find the chain
+	let parent = Object.getPrototypeOf(Ctor)
+	if (!parent || parent === baseClass) return null
+
+	// Check if the parent itself is a direct child of baseClass (i.e., 2nd level)
+	// We want to find the class between Ctor and baseClass
+	const chain: any[] = []
+	let current = parent
+	while (current && current !== baseClass && current !== Function.prototype) {
+		chain.push(current)
+		current = Object.getPrototypeOf(current)
+	}
+
+	// If the chain is empty or parent IS the baseClass, no intermediate
+	if (chain.length === 0 || current !== baseClass) return null
+
+	// The first entry in the chain is the direct parent of Ctor — that's our intermediate
+	const intermediate = chain[0]
+	const methods: string[] = []
+	const getters: string[] = []
+
+	// Collect only the methods/getters defined directly on the intermediate class
+	const proto = intermediate?.prototype
+	if (proto) {
+		for (const k of Object.getOwnPropertyNames(proto)) {
+			if (k === 'constructor' || k.startsWith('_')) continue
+			const desc = Object.getOwnPropertyDescriptor(proto, k)
+			if (!desc) continue
+			if (desc.get && !getters.includes(k)) getters.push(k)
+			else if (typeof desc.value === 'function' && !methods.includes(k)) methods.push(k)
+		}
+	}
+
+	return {
+		name: intermediate.name,
+		methods: methods.sort(),
+		getters: getters.sort(),
+	}
+}
+
 function getRegistryData(container: any, registryName: RegistryName, sections: (IntrospectionSection | 'description')[], noTitle = false, headingDepth = 1): { json: any; text: string } {
 	const registry = container[registryName]
 	const available: string[] = registry.available
@@ -327,6 +458,83 @@ function getRegistryData(container: any, registryName: RegistryName, sections: (
 		return { json: {}, text: `No ${registryName} are registered.` }
 	}
 
+	// When no section filters are specified, render a concise index (like describeAll)
+	// rather than full introspection for every single helper
+	if (sections.length === 0) {
+		const h = '#'.repeat(headingDepth)
+		const hSub = '#'.repeat(headingDepth + 1)
+		const jsonResult: Record<string, any> = {}
+		const textParts: string[] = [`${h} Available ${registryName} (${available.length})\n`]
+
+		// Show shared methods/getters from the base class at the top
+		const baseClass = registry.baseClass
+		if (baseClass) {
+			const shared = collectSharedMembers(baseClass)
+			const label = registryName === 'features' ? 'Feature'
+				: registryName === 'clients' ? 'Client'
+				: registryName === 'servers' ? 'Server'
+				: registryName[0]!.toUpperCase() + registryName.slice(1).replace(/s$/, '')
+
+			if (shared.getters.length) {
+				textParts.push(`**Shared ${label} Getters:** ${shared.getters.join(', ')}\n`)
+			}
+			if (shared.methods.length) {
+				textParts.push(`**Shared ${label} Methods:** ${shared.methods.map(m => m + '()').join(', ')}\n`)
+			}
+
+			jsonResult._shared = { methods: shared.methods, getters: shared.getters }
+		}
+
+		// Sort: core framework classes (direct children of baseClass) first, then the rest
+		const sorted = [...available].sort((a, b) => {
+			const aCtor = registry.lookup(a)
+			const bCtor = registry.lookup(b)
+			const aIsDirect = !findIntermediateParent(aCtor, baseClass)
+			const bIsDirect = !findIntermediateParent(bCtor, baseClass)
+			if (aIsDirect && !bIsDirect) return -1
+			if (!aIsDirect && bIsDirect) return 1
+			return 0
+		})
+
+		for (const id of sorted) {
+			const Ctor = registry.lookup(id)
+			const introspection = Ctor.introspect?.()
+			const description = introspection?.description || Ctor.description || 'No description provided'
+			// Take only the first 1-2 sentences as the summary
+			const summary = extractSummary(description)
+
+			const featureGetters = Object.keys(introspection?.getters || {}).sort()
+			const featureMethods = Object.keys(introspection?.methods || {}).sort()
+
+			// Detect intermediate parent class (e.g. RestClient between ElevenLabsClient and Client)
+			const intermediate = findIntermediateParent(Ctor, baseClass)
+
+			const entryJson: Record<string, any> = { description: summary, methods: featureMethods, getters: featureGetters }
+			if (intermediate) {
+				entryJson.extends = intermediate.name
+				entryJson.inheritedMethods = intermediate.methods
+				entryJson.inheritedGetters = intermediate.getters
+			}
+			jsonResult[id] = entryJson
+
+			const extendsLine = intermediate ? `\n> extends ${intermediate.name}\n` : ''
+
+			const memberLines: string[] = []
+			if (featureGetters.length) memberLines.push(`  getters: ${featureGetters.join(', ')}`)
+			if (featureMethods.length) memberLines.push(`  methods: ${featureMethods.map(m => m + '()').join(', ')}`)
+			if (intermediate) {
+				if (intermediate.getters.length) memberLines.push(`  inherited getters: ${intermediate.getters.join(', ')}`)
+				if (intermediate.methods.length) memberLines.push(`  inherited methods: ${intermediate.methods.map(m => m + '()').join(', ')}`)
+			}
+
+			const memberBlock = memberLines.length ? '\n' + memberLines.join('\n') + '\n' : ''
+			textParts.push(`${hSub} ${id}${extendsLine}\n${summary}\n${memberBlock}`)
+		}
+
+		return { json: jsonResult, text: textParts.join('\n') }
+	}
+
+	// When specific sections are requested, render full detail for each helper
 	const jsonResult: Record<string, any> = {}
 	const textParts: string[] = []
 	for (const id of available) {
@@ -338,13 +546,140 @@ function getRegistryData(container: any, registryName: RegistryName, sections: (
 	return { json: jsonResult, text: textParts.join('\n\n---\n\n') }
 }
 
+/** Known top-level helper base class names — anything above these is "shared" */
+const BASE_CLASS_NAMES = new Set(['Helper', 'Feature', 'Client', 'Server'])
+
+/**
+ * Build a concise summary block for an individual helper listing its interface at a glance.
+ * Shows extends line if there's an intermediate parent, then own methods/getters,
+ * then inherited methods/getters from the intermediate parent.
+ */
+function buildHelperSummary(Ctor: any): string {
+	const introspection = Ctor.introspect?.()
+	const ownMethods = Object.keys(introspection?.methods || {}).sort()
+	const ownGetters = Object.keys(introspection?.getters || {}).sort()
+
+	// Walk up the prototype chain to find an intermediate parent
+	const chain: any[] = []
+	let current = Object.getPrototypeOf(Ctor)
+	while (current && current.name && !BASE_CLASS_NAMES.has(current.name) && current !== Function.prototype) {
+		chain.push(current)
+		current = Object.getPrototypeOf(current)
+	}
+
+	const lines: string[] = []
+
+	if (chain.length > 0) {
+		lines.push(`> extends ${chain[0].name}`)
+	}
+
+	if (ownGetters.length) lines.push(`getters: ${ownGetters.join(', ')}`)
+	if (ownMethods.length) lines.push(`methods: ${ownMethods.map(m => m + '()').join(', ')}`)
+
+	// Collect inherited members from intermediate parent(s)
+	for (const parent of chain) {
+		const parentIntrospection = parent.introspect?.()
+		const inheritedMethods = Object.keys(parentIntrospection?.methods || {}).sort()
+		const inheritedGetters = Object.keys(parentIntrospection?.getters || {}).sort()
+		if (inheritedGetters.length) lines.push(`inherited getters (${parent.name}): ${inheritedGetters.join(', ')}`)
+		if (inheritedMethods.length) lines.push(`inherited methods (${parent.name}): ${inheritedMethods.map(m => m + '()').join(', ')}`)
+	}
+
+	return lines.join('\n')
+}
+
+function getMemberData(container: any, registryName: RegistryName, id: string, member: string, memberType: 'method' | 'getter', headingDepth = 1): { json: any; text: string } {
+	const registry = container[registryName]
+	const Ctor = registry.lookup(id)
+	const introspection = Ctor.introspect?.()
+	const h = '#'.repeat(headingDepth)
+	const hSub = '#'.repeat(headingDepth + 1)
+
+	if (memberType === 'method') {
+		const method = introspection?.methods?.[member] as MethodIntrospection | undefined
+		if (!method) return { json: {}, text: `No introspection data for ${id}.${member}()` }
+
+		const parts: string[] = []
+		parts.push(`${h} ${id}.${member}()`)
+		parts.push(`> method on **${introspection.className || id}**`)
+
+		if (method.description) parts.push(method.description)
+
+		// Parameters
+		const paramEntries = Object.entries(method.parameters || {})
+		if (paramEntries.length > 0) {
+			const paramLines = [`${hSub} Parameters`, '']
+			for (const [name, info] of paramEntries) {
+				const req = (method.required || []).includes(name) ? ' *(required)*' : ''
+				paramLines.push(`- **${name}** \`${info.type}\`${req}${info.description ? ' — ' + info.description : ''}`)
+				// Nested properties (e.g. options objects)
+				if (info.properties) {
+					for (const [propName, propInfo] of Object.entries(info.properties)) {
+						paramLines.push(`  - **${propName}** \`${propInfo.type}\`${propInfo.description ? ' — ' + propInfo.description : ''}`)
+					}
+				}
+			}
+			parts.push(paramLines.join('\n'))
+		}
+
+		// Returns
+		if (method.returns && method.returns !== 'void') {
+			parts.push(`${hSub} Returns\n\n\`${method.returns}\``)
+		}
+
+		// Examples
+		if (method.examples?.length) {
+			parts.push(`${hSub} Examples`)
+			for (const ex of method.examples) {
+				parts.push(`\`\`\`${ex.language || 'typescript'}\n${ex.code}\n\`\`\``)
+			}
+		}
+
+		return { json: { [member]: method, _helper: id, _type: 'method' }, text: parts.join('\n\n') }
+	}
+
+	// Getter
+	const getter = introspection?.getters?.[member] as GetterIntrospection | undefined
+	if (!getter) return { json: {}, text: `No introspection data for ${id}.${member}` }
+
+	const parts: string[] = []
+	parts.push(`${h} ${id}.${member}`)
+	parts.push(`> getter on **${introspection.className || id}** — returns \`${getter.returns || 'unknown'}\``)
+
+	if (getter.description) parts.push(getter.description)
+
+	if (getter.examples?.length) {
+		parts.push(`${hSub} Examples`)
+		for (const ex of getter.examples) {
+			parts.push(`\`\`\`${ex.language || 'typescript'}\n${ex.code}\n\`\`\``)
+		}
+	}
+
+	return { json: { [member]: getter, _helper: id, _type: 'getter' }, text: parts.join('\n\n') }
+}
+
 function getHelperData(container: any, registryName: RegistryName, id: string, sections: (IntrospectionSection | 'description')[], noTitle = false, headingDepth = 1): { json: any; text: string } {
 	const registry = container[registryName]
 	const Ctor = registry.lookup(id)
+	const text = renderHelperText(Ctor, sections, noTitle, headingDepth)
+
+	// Inject summary after the title + description block for full (no-section) renders
+	let finalText = text
+	if (sections.length === 0 && !noTitle) {
+		const summary = buildHelperSummary(Ctor)
+		if (summary) {
+			// Find the first ## heading and insert the summary before it
+			const sectionHeading = '#'.repeat(headingDepth + 1) + ' '
+			const idx = text.indexOf('\n' + sectionHeading)
+			if (idx >= 0) {
+				finalText = text.slice(0, idx) + '\n\n' + summary + '\n' + text.slice(idx)
+			}
+		}
+	}
 
 	return {
 		json: renderHelperJson(Ctor, sections, noTitle),
-		text: renderHelperText(Ctor, sections, noTitle, headingDepth),
+		text: finalText,
 	}
 }
 
@@ -405,6 +740,8 @@ export default async function describe(options: z.infer<typeof argsSchema>, cont
 				return getRegistryData(container, item.name, sections, noTitle, headingDepth)
 			case 'helper':
 				return getHelperData(container, item.registry, item.id, sections, noTitle, headingDepth)
+			case 'member':
+				return getMemberData(container, item.registry, item.id, item.member, item.memberType, headingDepth)
 		}
 	}
 

package/src/commands/help.ts

@@ -13,7 +13,7 @@ export const argsSchema = CommandOptionsSchema.extend({})
 
 /** Hidden option prefixes — legacy aliases that shouldn't clutter help output. */
 const HIDDEN_PREFIXES = ['only-']
-const HIDDEN_KEYS = new Set(['_', 'name', '_cacheKey'])
+const HIDDEN_KEYS = new Set(['_', 'name', '_cacheKey', 'dispatchSource'])
 
 /**
  * Extract CLI option info from a Zod schema.
@@ -176,17 +176,43 @@ export default async function help(_options: z.infer<typeof argsSchema>, context
 		console.log()
 		console.log(c.white('  Usage: ') + c.cyan('luca') + c.dim(' <command|file> [options]'))
 		console.log()
+		const allNames = (container.commands.available as string[]).filter((n: string) => n !== 'help')
+		const maxNameLen = Math.max(...allNames.map((n: string) => n.length)) + 2
+
+		const sources = (container as any)._commandSources as
+			| { builtinCommands: Set<string>; projectCommands: Set<string>; userCommands: Set<string> }
+			| undefined
+
+		const printCommands = (names: string[]) => {
+			for (const name of names) {
+				const Cmd = container.commands.lookup(name) as any
+				const desc = Cmd.commandDescription || ''
+				console.log(`    ${c.cyan(name.padEnd(maxNameLen))} ${c.dim(desc)}`)
+			}
+		}
+
+		// Built-in commands
+		const builtinNames = sources
+			? allNames.filter((n) => sources.builtinCommands.has(n))
+			: allNames
 		console.log(c.white('  Commands:'))
 		console.log()
+		printCommands(builtinNames)
+
+		// Project-local commands
+		if (sources && sources.projectCommands.size > 0) {
+			console.log()
+			console.log(c.white('  Project Commands') + c.dim(' (./commands/*)'))
+			console.log()
+			printCommands(allNames.filter((n) => sources.projectCommands.has(n)))
+		}
 
-		// Dynamic padding based on longest command name
-		const commandNames = (container.commands.available as string[]).filter((n: string) => n !== 'help')
-		const maxNameLen = Math.max(...commandNames.map((n: string) => n.length)) + 2
-
-		for (const name of commandNames) {
-			const Cmd = container.commands.lookup(name) as any
-			const desc = Cmd.commandDescription || ''
-			console.log(`    ${c.cyan(name.padEnd(maxNameLen))} ${c.dim(desc)}`)
+		// User-level commands
+		if (sources && sources.userCommands.size > 0) {
+			console.log()
+			console.log(c.white('  User Commands') + c.dim(' (~/.luca/commands/*)'))
+			console.log()
+			printCommands(allNames.filter((n) => sources.userCommands.has(n)))
 		}
 
 		console.log()

package/src/commands/index.ts

@@ -13,3 +13,6 @@ import './eval.js'
 import './help.js'
 import './scaffold.js'
 import './introspect.js'
+import './save-api-docs.js'
+import './bootstrap.js'
+import './select.js'

package/src/commands/introspect.ts

@@ -15,8 +15,81 @@ export const argsSchema = CommandOptionsSchema.extend({
 	output: z.string().optional().describe('Output file path (default: features/introspection.generated.ts)'),
 	'dry-run': z.boolean().default(false).describe('Preview without writing'),
 	'include-private': z.boolean().default(false).describe('Include private methods in output'),
+	lint: z.boolean().default(false).describe('Warn about undocumented getters, methods, options, and class descriptions'),
 })
 
+function lintResults(results: any[]) {
+	type LintWarning = { helper: string; category: string; member: string; message: string }
+	const warnings: LintWarning[] = []
+
+	for (const result of results) {
+		const helper = result.className || result.id
+
+		// Class-level description
+		if (!result.description || result.description === `${result.className} helper`) {
+			warnings.push({ helper, category: 'class', member: '', message: 'Missing class description (add a JSDoc block above the class)' })
+		}
+
+		// Methods
+		for (const [name, method] of Object.entries(result.methods || {}) as [string, any][]) {
+			if (!method.description) {
+				warnings.push({ helper, category: 'method', member: name, message: 'Missing JSDoc description' })
+			}
+			// Check for undocumented parameters (generic fallback description)
+			for (const [paramName, param] of Object.entries(method.parameters || {}) as [string, any][]) {
+				if (param.description === `Parameter ${paramName}`) {
+					warnings.push({ helper, category: 'method', member: `${name}(@param ${paramName})`, message: 'Missing @param description' })
+				}
+			}
+			if (method.returns === 'void' || method.returns === 'any') {
+				// not necessarily a problem, skip
+			}
+		}
+
+		// Getters
+		for (const [name, getter] of Object.entries(result.getters || {}) as [string, any][]) {
+			if (!getter.description) {
+				warnings.push({ helper, category: 'getter', member: name, message: 'Missing JSDoc description' })
+			}
+		}
+
+		// Options (populated at runtime from Zod, but build-time scan may have empty options)
+		// We check if options exist and have empty descriptions
+		for (const [name, opt] of Object.entries(result.options || {}) as [string, any][]) {
+			if (!opt.description) {
+				warnings.push({ helper, category: 'option', member: name, message: 'Missing description (add .describe() to the Zod schema field)' })
+			}
+		}
+	}
+
+	return warnings
+}
+
+function printLintReport(warnings: ReturnType<typeof lintResults>, label?: string) {
+	if (warnings.length === 0) {
+		console.log(label ? `  ${label}: No lint warnings.` : 'No lint warnings.')
+		return 0
+	}
+
+	// Group by helper
+	const byHelper = new Map<string, typeof warnings>()
+	for (const w of warnings) {
+		if (!byHelper.has(w.helper)) byHelper.set(w.helper, [])
+		byHelper.get(w.helper)!.push(w)
+	}
+
+	console.log(label ? `\n  ${label}: ${warnings.length} lint warning(s)` : `\n${warnings.length} lint warning(s)`)
+	for (const [helper, ws] of byHelper) {
+		console.log(`\n  ${helper}:`)
+		for (const w of ws) {
+			const target = w.member ? `${w.category} ${w.member}` : w.category
+			console.log(`    - [${target}] ${w.message}`)
+		}
+	}
+
+	return warnings.length
+}
+
 async function introspect(options: z.infer<typeof argsSchema>, context: ContainerContext) {
 	const container = context.container as any
 	const { fs, paths } = container
@@ -33,7 +106,7 @@ async function introspect(options: z.infer<typeof argsSchema>, context: Containe
 		const targets = [
 			{
 				name: 'node',
-				src: ['src/node/features', 'src/servers', 'src/container.ts', 'src/node/container.ts'],
+				src: ['src/node/features', 'src/clients', 'src/servers', 'src/container.ts', 'src/node/container.ts'],
 				outputPath: 'src/introspection/generated.node.ts',
 			},
 			{
@@ -43,11 +116,13 @@ async function introspect(options: z.infer<typeof argsSchema>, context: Containe
 			},
 			{
 				name: 'agi',
-				src: ['src/node/features', 'src/servers', 'src/agi/features', 'src/container.ts', 'src/node/container.ts', 'src/agi/container.server.ts'],
+				src: ['src/node/features', 'src/clients', 'src/servers', 'src/agi/features', 'src/container.ts', 'src/node/container.ts', 'src/agi/container.server.ts'],
 				outputPath: 'src/introspection/generated.agi.ts',
 			},
 		]
 
+		let totalWarnings = 0
+
 		for (const target of targets) {
 			console.log(`\nGenerating ${target.name} introspection data...`)
 			console.log(`  Sources: ${target.src.join(', ')}`)
@@ -72,9 +147,18 @@ async function introspect(options: z.infer<typeof argsSchema>, context: Containe
 			} else {
 				console.log(`  Wrote ${target.outputPath}`)
 			}
+
+			if (options.lint) {
+				const scanResults = scanner.state.get('scanResults') || []
+				const warnings = lintResults(scanResults)
+				totalWarnings += printLintReport(warnings, target.name)
+			}
 		}
 
 		console.log('\nAll introspection data generated.')
+		if (options.lint && totalWarnings > 0) {
+			console.log(`\nTotal: ${totalWarnings} lint warning(s) across all targets.`)
+		}
 		return
 	}
 
@@ -119,6 +203,12 @@ async function introspect(options: z.infer<typeof argsSchema>, context: Containe
 	} else {
 		console.log(`Wrote ${outputPath}`)
 	}
+
+	if (options.lint) {
+		const scanResults = scanner.state.get('scanResults') || []
+		const warnings = lintResults(scanResults)
+		printLintReport(warnings)
+	}
 }
 
 commands.registerHandler('introspect', {

package/src/commands/prompt.ts

@@ -12,8 +12,7 @@ declare module '../command.js' {
 
 export const argsSchema = CommandOptionsSchema.extend({
 	model: z.string().optional().describe('Override the LLM model (assistant mode only)'),
-	folder: z.string().default('assistants').describe('Directory containing assistant definitions'),
-	'preserve-frontmatter': z.boolean().default(false).describe('Keep YAML frontmatter in the prompt instead of stripping it'),
+'preserve-frontmatter': z.boolean().default(false).describe('Keep YAML frontmatter in the prompt instead of stripping it'),
 	'permission-mode': z.enum(['default', 'acceptEdits', 'bypassPermissions', 'plan']).default('acceptEdits').describe('Permission mode for CLI agents (default: acceptEdits)'),
 	'in-folder': z.string().optional().describe('Run the CLI agent in this directory (resolved via container.paths)'),
 	'out-file': z.string().optional().describe('Save session output as a markdown file'),
@@ -144,8 +143,8 @@ async function runClaudeOrCodex(target: 'claude' | 'codex', promptContent: strin
 
 async function runAssistant(name: string, promptContent: string, options: z.infer<typeof argsSchema>, container: any): Promise<RunStats> {
 	const ui = container.feature('ui')
-	const manager = container.feature('assistantsManager', { folder: options.folder })
-	manager.discover()
+	const manager = container.feature('assistantsManager')
+	await manager.discover()
 
 	const entry = manager.get(name)
 	if (!entry) {
@@ -335,8 +334,8 @@ async function runParallel(
 		})
 	} else {
 		// Assistant targets
-		const manager = container.feature('assistantsManager', { folder: options.folder })
-		manager.discover()
+		const manager = container.feature('assistantsManager')
+		await manager.discover()
 
 		const entry = manager.get(target)
 		if (!entry) {