@soederpop/luca 0.0.5 → 0.0.7

package/src/commands/describe.ts

@@ -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. */
@@ -75,6 +75,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.
@@ -319,6 +337,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 +416,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 +504,70 @@ 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 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,
 	}
 }
 

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) {

package/src/commands/run.ts

@@ -13,6 +13,7 @@ export const argsSchema = CommandOptionsSchema.extend({
 	safe: z.boolean().default(false).describe('Require approval before each code block (markdown mode)'),
 	console: z.boolean().default(false).describe('Start an interactive REPL after executing a markdown file, with all accumulated context'),
 	onlySections: z.string().optional().describe('Comma-separated list of section headings to run (case-insensitive, markdown only)'),
+	dontInjectContext: z.boolean().default(false).describe('Skip auto-injecting container context into scripts (run with plain bun instead)'),
 })
 
 function resolveScript(ref: string, context: ContainerContext): string | null {
@@ -87,6 +88,7 @@ async function runMarkdown(scriptPath: string, options: z.infer<typeof argsSchem
 		setTimeout, clearTimeout, setInterval, clearInterval,
 		fetch, URL, URLSearchParams,
 		...container.context,
+		$doc: doc
 	})
 
 	// ─── Parse and register ## Blocks section ──────────────────────────
@@ -173,20 +175,41 @@ async function runMarkdown(scriptPath: string, options: z.infer<typeof argsSchem
 	return shared
 }
 
-async function runScript(scriptPath: string, context: ContainerContext) {
+async function runScript(scriptPath: string, context: ContainerContext, options: { dontInjectContext?: boolean } = {}) {
 	const container = context.container as any
 
-	const { exitCode, stderr } = await container.proc.execAndCapture(`bun run ${scriptPath}`, {
-		onOutput: (data: string) => process.stdout.write(data),
-		onError: (data: string) => process.stderr.write(data),
-	})
+	if (options.dontInjectContext) {
+		const { exitCode, stderr } = await container.proc.execAndCapture(`bun run ${scriptPath}`, {
+			onOutput: (data: string) => process.stdout.write(data),
+			onError: (data: string) => process.stderr.write(data),
+		})
+
+		if (exitCode === 0) return
 
-	if (exitCode === 0) return
+		console.error(`\nScript failed with exit code ${exitCode}.\n`)
+		if (stderr.length) {
+			console.error(stderr)
+		}
+		return
+	}
 
-	console.error(`\nScript failed with exit code ${exitCode}.\n`)
-	if (stderr.length) {
-		console.error(stderr)
+	const vm = container.feature('vm')
+	const esbuild = container.feature('esbuild')
+	const raw = container.fs.readFile(scriptPath)
+	const { code } = esbuild.transformSync(raw, { format: 'cjs' })
+
+	const ctx = {
+		require: vm.createRequireFor(scriptPath),
+		exports: {},
+		module: { exports: {} },
+		console,
+		setTimeout, setInterval, clearTimeout, clearInterval,
+		process, Buffer, URL, URLSearchParams,
+		fetch,
+		...container.context,
 	}
+
+	await vm.run(code, ctx)
 }
 
 async function diagnoseError(_scriptPath: string, error: Error, _context: ContainerContext) {
@@ -236,7 +259,7 @@ export default async function run(options: z.infer<typeof argsSchema>, context:
 				})
 			}
 		} else {
-			await runScript(scriptPath, context)
+			await runScript(scriptPath, context, { dontInjectContext: options.dontInjectContext })
 		}
 	} catch (err: any) {
 		await diagnoseError(scriptPath, err instanceof Error ? err : new Error(String(err)), context)

package/src/commands/save-api-docs.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		introspect: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({ 
+	outputPath: z.string().default('docs/luca').describe('The path to save generated API docs to')
+})
+
+export async function apiDocs(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const { container } = context
+	await container.helpers.discoverAll()
+	const outputFolder = options.outputPath ? container.paths.resolve(options.outputPath) : container.paths.resolve('docs','luca')
+
+	await container.fs.ensureFolder(
+		outputFolder
+	)
+
+	const mkPath = (...args) => container.paths.resolve(outputFolder, ...args)
+
+	const result = await container.fs.writeFileAsync(mkPath('agi-container.md'), container.inspectAsText())
+
+	for(let reg of ['features','clients','servers']) {
+		const helperIds = container[reg].available
+		const folder = mkPath(reg) 
+		await container.fs.ensureFolder(folder)
+
+		await Promise.all(
+			helperIds.map((helperId) => container.fs.writeFileAsync(
+				container.paths.resolve(folder, `${helperId}.md`),
+				container[reg].describe(helperId)
+			))
+		)
+	}
+
+	container.ui.print.green(`Finished saving API Docs`)
+}
+
+commands.registerHandler('api-docs', {
+	description: 'Save the helper introspection() content as markdown API docs in docs/luca',
+	argsSchema,
+	handler: apiDocs,
+})