@soederpop/luca 0.0.31 → 0.0.34

package/src/cli/build-info.ts

@@ -1,4 +1,4 @@
 // Generated at compile time — do not edit manually
-export const BUILD_SHA = 'ff23ed7'
+export const BUILD_SHA = 'd3e8b52'
 export const BUILD_BRANCH = 'main'
-export const BUILD_DATE = '2026-03-24T09:08:07Z'
+export const BUILD_DATE = '2026-03-26T03:30:23Z'

package/src/cli/cli.ts

@@ -37,9 +37,15 @@ async function main() {
 	// helpers.discoverAll() which registers project commands early
 	const builtinCommands = new Set(container.commands.available as string[])
 
+	// Load global CLI module (~/.luca/luca.cli.ts) before project-level —
+	// lets users set up global helpers, discovery roots, etc.
+	let done = t('loadGlobalCliModule')
+	await loadCliModule(join(homedir(), '.luca', 'luca.cli.ts'))
+	done()
+
 	// Load project-level CLI module (luca.cli.ts) for container customization
-	let done = t('loadCliModule')
-	await loadCliModule()
+	done = t('loadCliModule')
+	await loadCliModule(container.paths.resolve('luca.cli.ts'))
 	done()
 
 	// Discover project-local commands (commands/ or src/commands/)
@@ -51,10 +57,10 @@ async function main() {
 	const afterProject = new Set(container.commands.available as string[])
 	const projectCommands = new Set([...afterProject].filter((n) => !builtinCommands.has(n)))
 
-	// Discover user-level commands (~/.luca/commands/)
-	done = t('discoverUserCommands')
+	// Discover user-level helpers (~/.luca/{features,clients,servers,commands,selectors}/)
+	done = t('discoverUserHelpers')
 	if (discovery !== 'disable' && discovery !== 'no-home') {
-		await discoverUserCommands()
+		await discoverUserHelpers()
 	}
 	done()
 	const afterUser = new Set(container.commands.available as string[])
@@ -135,8 +141,7 @@ function resolveScript(ref: string, container: any) {
 	return null
 }
 
-async function loadCliModule() {
-	const modulePath = container.paths.resolve('luca.cli.ts')
+async function loadCliModule(modulePath: string) {
 	if (!container.fs.exists(modulePath)) return
 
 	// Use the helpers feature to load the module — it handles the native import
@@ -181,13 +186,17 @@ async function loadProjectIntrospection() {
 	}
 }
 
-async function discoverUserCommands() {
-	const dir = join(homedir(), '.luca', 'commands')
+const DISCOVERABLE_TYPES = ['features', 'clients', 'servers', 'commands', 'selectors'] as const
 
-	if (container.fs.exists(dir)) {
-		// Route through helpers for consistent dedup and VM/native handling
-		const helpers = container.feature('helpers') as any
-		await helpers.discover('commands', { directory: dir })
+async function discoverUserHelpers() {
+	const lucaHome = join(homedir(), '.luca')
+	const helpers = container.feature('helpers') as any
+
+	for (const type of DISCOVERABLE_TYPES) {
+		const dir = join(lucaHome, type)
+		if (container.fs.exists(dir)) {
+			await helpers.discover(type, { directory: dir })
+		}
 	}
 }
 

package/src/commands/bootstrap.ts

@@ -3,7 +3,6 @@ import { commands } from '../command.js'
 import { CommandOptionsSchema } from '../schemas/base.js'
 import type { ContainerContext } from '../container.js'
 import { bootstrapFiles, bootstrapTemplates, bootstrapExamples, bootstrapTutorials } from '../bootstrap/generated.js'
-import { apiDocs } from './save-api-docs.js'
 import { generateScaffold } from '../scaffolds/template.js'
 
 declare module '../command.js' {
@@ -14,16 +13,34 @@ declare module '../command.js' {
 
 export const argsSchema = CommandOptionsSchema.extend({
 	output: z.string().default('.').describe('Output folder path (defaults to cwd)'),
+	'update-skill': z.boolean().default(false).describe('Only update .claude/skills/luca-framework in the current project'),
 })
 
 async function bootstrap(options: z.infer<typeof argsSchema>, context: ContainerContext) {
 	const { container } = context
 	const args = container.argv._ as string[]
-	const outputDir = container.paths.resolve(args[1] || options.output)
 	const fs = container.feature('fs')
 	const ui = container.feature('ui')
 	const proc = container.feature('proc')
 
+	// ── --update-skill: refresh skill files in the current project ──
+	if (options['update-skill']) {
+		return await updateSkill(container, fs, ui)
+	}
+
+	// Require an explicit target — don't silently bootstrap into cwd
+	let target = args[1] || (options.output !== '.' ? options.output : '')
+
+	if (!target) {
+		const answer = await ui.askQuestion('Project name (folder to create):')
+		target = answer?.question?.trim()
+		if (!target) {
+			ui.print.red('\n  No project name given, aborting.\n')
+			return
+		}
+	}
+
+	const outputDir = container.paths.resolve(target)
 	await fs.ensureFolder(outputDir)
 	const mkPath = (...segments: string[]) => container.paths.resolve(outputDir, ...segments)
 
@@ -48,10 +65,6 @@ async function bootstrap(options: z.infer<typeof argsSchema>, context: Container
 	await fs.ensureFolder(skillDir)
 	await writeFile(fs, ui, container.paths.resolve(skillDir, 'SKILL.md'), bootstrapFiles['SKILL'] || '', '.claude/skills/luca-framework/SKILL.md')
 
-	ui.print.cyan('  Generating API docs...')
-	const apiDocsPath = container.paths.resolve(skillDir, 'references', 'api-docs')
-	await apiDocs({ _: [], outputPath: apiDocsPath }, context)
-
 	// ── 3b. examples and tutorials ─────────────────────────────────
 	const examplesDir = container.paths.resolve(skillDir, 'references', 'examples')
 	await fs.ensureFolder(examplesDir)
@@ -146,6 +159,36 @@ async function bootstrap(options: z.infer<typeof argsSchema>, context: Container
 
 // ── Helpers ──────────────────────────────────────────────────────────
 
+async function updateSkill(container: any, fs: any, ui: any) {
+	const skillDir = container.paths.resolve('.claude', 'skills', 'luca-framework')
+
+	// Wipe existing skill directory so stale files don't linger
+	if (fs.exists(skillDir)) {
+		await fs.rmdir(skillDir)
+	}
+
+	await fs.ensureFolder(skillDir)
+	await writeFile(fs, ui, container.paths.resolve(skillDir, 'SKILL.md'), bootstrapFiles['SKILL'] || '', '.claude/skills/luca-framework/SKILL.md')
+
+	const examplesDir = container.paths.resolve(skillDir, 'references', 'examples')
+	await fs.ensureFolder(examplesDir)
+	for (const [filename, content] of Object.entries(bootstrapExamples)) {
+		await fs.writeFileAsync(container.paths.resolve(examplesDir, filename), content)
+	}
+	ui.print.cyan(`  Writing ${Object.keys(bootstrapExamples).length} example docs...`)
+
+	const tutorialsDir = container.paths.resolve(skillDir, 'references', 'tutorials')
+	await fs.ensureFolder(tutorialsDir)
+	for (const [filename, content] of Object.entries(bootstrapTutorials)) {
+		await fs.writeFileAsync(container.paths.resolve(tutorialsDir, filename), content)
+	}
+	ui.print.cyan(`  Writing ${Object.keys(bootstrapTutorials).length} tutorial docs...`)
+
+	ui.print('')
+	ui.print.green('  ✓ Skill updated!')
+	ui.print('')
+}
+
 async function writeFile(fs: any, ui: any, path: string, content: string, label: string) {
 	ui.print.cyan(`  Writing ${label}...`)
 	await fs.writeFileAsync(path, content)

package/src/commands/code.ts

@@ -0,0 +1,369 @@
+import { z } from 'zod'
+import * as readline from 'readline'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+import type { AGIContainer, AGIFeatures } from '../agi/container.server.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		code: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	model: z.string().optional().describe('Override the LLM model'),
+	local: z.boolean().default(false).describe('Use a local API server'),
+	prompt: z.string().optional().describe('Path to a markdown file or inline text for the system prompt'),
+	allowAll: z.boolean().default(false).describe('Start with all permissions set to allow (fully autonomous)'),
+	denyWrites: z.boolean().default(false).describe('Deny all write/delete/move operations'),
+	skills: z.string().optional().describe('Comma-separated list of additional skill names to load'),
+})
+
+export const positionals = ['prompt']
+
+export default async function code(options: z.infer<typeof argsSchema>, context: ContainerContext<AGIFeatures>) {
+	const container = context.container as AGIContainer
+	const ui = container.feature('ui')
+	const colors = ui.colors
+	const fs = container.feature('fs')
+
+	// ── Resolve system prompt ──────────────────────────────────────────────
+	// The lucaCoder feature has a solid default system prompt. Only override
+	// if the user explicitly provides one via --prompt.
+	let systemPrompt: string | undefined
+
+	if (options.prompt) {
+		const resolved = container.paths.resolve(options.prompt)
+		if (fs.exists(resolved)) {
+			systemPrompt = fs.readFile(resolved)
+		} else if (!options.prompt.endsWith('.md')) {
+			systemPrompt = options.prompt
+		} else {
+			console.error(colors.red(`File not found: ${resolved}`))
+			process.exit(1)
+		}
+	}
+
+	// ── Permission profile ─────────────────────────────────────────────────
+	const readTools = ['readFile', 'searchFiles', 'findFiles', 'listDirectory', 'fileInfo']
+	const writeTools = ['writeFile', 'editFile', 'createDirectory', 'moveFile', 'copyFile', 'bash']
+	const dangerTools = ['deleteFile']
+	const skillTools = ['searchAvailableSkills', 'loadSkill', 'askSkillBasedQuestion']
+
+	const permissions: Record<string, 'allow' | 'ask' | 'deny'> = {}
+
+	// Skill tools are always allowed — they're read-only discovery operations
+	for (const t of skillTools) permissions[t] = 'allow'
+
+	if (options.allowAll) {
+		for (const t of [...readTools, ...writeTools, ...dangerTools]) permissions[t] = 'allow'
+	} else if (options.denyWrites) {
+		for (const t of readTools) permissions[t] = 'allow'
+		for (const t of writeTools) permissions[t] = 'deny'
+		for (const t of dangerTools) permissions[t] = 'deny'
+	} else {
+		// Default: reads are free, writes need approval, danger is denied
+		for (const t of readTools) permissions[t] = 'allow'
+		for (const t of writeTools) permissions[t] = 'ask'
+		for (const t of dangerTools) permissions[t] = 'deny'
+	}
+
+	// ── Parse extra skills ────────────────────────────────────────────────
+	const extraSkills = options.skills ? options.skills.split(',').map((s: string) => s.trim()).filter(Boolean) : undefined
+
+	// ── Create the luca coder ──────────────────────────────────────────────
+	const coder = container.feature('lucaCoder', {
+		tools: ['fileTools'],
+		permissions,
+		defaultPermission: 'ask',
+		systemPrompt,
+		model: options.model,
+		local: options.local,
+		skills: extraSkills,
+	})
+
+	// ── UI setup ───────────────────────────────────────────────────────────
+	const ink = container.feature('ink', { enable: true })
+	await ink.loadModules()
+	const React = ink.React
+	const { Text } = ink.components
+	const inkModule = await import('ink')
+
+	let responseBuffer = ''
+	let inkInstance: any = null
+
+	function mdElement(content: string) {
+		const rendered = content ? String(ui.markdown(content)).trimEnd() : ''
+		return React.createElement(Text, null, rendered)
+	}
+
+	// Wire events on coder before starting (it forwards from inner assistant)
+	coder.on('chunk', (text: string) => {
+		responseBuffer += text
+		if (!inkInstance) {
+			process.stdout.write('\n')
+			inkInstance = inkModule.render(mdElement(responseBuffer), { patchConsole: false })
+		} else {
+			inkInstance.rerender(mdElement(responseBuffer))
+		}
+	})
+
+	coder.on('toolCall', (toolName: string, args: any) => {
+		if (inkInstance) { inkInstance.unmount(); inkInstance = null }
+		responseBuffer = ''
+		const argsStr = JSON.stringify(args).slice(0, 120)
+		process.stdout.write(colors.dim(`\n  ⟳ ${toolName}`) + colors.dim(`(${argsStr})\n`))
+	})
+
+	coder.on('toolResult', (toolName: string, result: any) => {
+		const preview = typeof result === 'string' ? result.slice(0, 100) : JSON.stringify(result).slice(0, 100)
+		process.stdout.write(colors.green(`  ✓ ${toolName}`) + colors.dim(` → ${preview}${preview.length >= 100 ? '…' : ''}\n`))
+	})
+
+	coder.on('toolError', (toolName: string, error: any) => {
+		const msg = error?.message || String(error)
+		process.stdout.write(colors.red(`  ✗ ${toolName}: ${msg}\n`))
+	})
+
+	coder.on('response', () => {
+		if (inkInstance) { inkInstance.unmount(); inkInstance = null }
+		responseBuffer = ''
+		process.stdout.write('\n')
+	})
+
+	// Start the coder (creates inner assistant, registers bash tool, stacks fileTools, loads skills)
+	await coder.start()
+
+	// ── Permission request handler ─────────────────────────────────────────
+	coder.on('permissionRequest', ({ id, toolName, args }: { id: string; toolName: string; args: Record<string, any> }) => {
+		if (inkInstance) { inkInstance.unmount(); inkInstance = null }
+
+		const argsPreview = Object.entries(args)
+			.map(([k, v]) => {
+				const val = typeof v === 'string'
+					? (v.length > 60 ? v.slice(0, 57) + '...' : v)
+					: JSON.stringify(v)
+				return `    ${colors.dim(k)}: ${val}`
+			})
+			.join('\n')
+
+		process.stdout.write('\n')
+		process.stdout.write(colors.yellow(`  ⚡ Permission required: ${colors.bold(toolName)}\n`))
+		if (argsPreview) process.stdout.write(argsPreview + '\n')
+		process.stdout.write(colors.dim(`\n  [y] approve  [n] deny  [a] allow all future ${toolName} calls\n`))
+
+		promptApproval(id, toolName)
+	})
+
+	coder.on('toolBlocked', (toolName: string, reason: string) => {
+		process.stdout.write(colors.red(`  ✗ ${toolName} blocked (${reason})\n`))
+	})
+
+	// ── Readline ───────────────────────────────────────────────────────────
+	let rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	})
+	let rlClosed = false
+	rl.on('close', () => { rlClosed = true })
+
+	function ensureRl() {
+		if (rlClosed) {
+			rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+			rlClosed = false
+			rl.on('close', () => { rlClosed = true })
+		}
+	}
+
+	function prompt(): Promise<string> {
+		return new Promise((resolve) => {
+			ensureRl()
+			rl.question(colors.cyan('\n  code > '), (answer: string) => resolve(answer.trim()))
+		})
+	}
+
+	function promptApproval(id: string, toolName: string) {
+		ensureRl()
+		rl.question(colors.yellow('  > '), (answer: string) => {
+			const a = answer.trim().toLowerCase()
+			if (a === 'y' || a === 'yes') {
+				coder.approve(id)
+			} else if (a === 'a' || a === 'always') {
+				coder.permitTool(toolName)
+				coder.approve(id)
+				process.stdout.write(colors.green(`  ✓ ${toolName} will be auto-approved from now on\n`))
+			} else {
+				coder.deny(id)
+			}
+		})
+	}
+
+	// ── Piped stdin mode ──────────────────────────────────────────────────
+	// When stdin is piped (e.g. `cat prompt.md | luca code`), read all of
+	// stdin as the initial prompt, run it, print the result, and exit.
+	if (!process.stdin.isTTY) {
+		const chunks: Buffer[] = []
+		for await (const chunk of process.stdin) {
+			chunks.push(chunk as Buffer)
+		}
+		const pipedInput = Buffer.concat(chunks).toString('utf-8').trim()
+
+		if (!pipedInput) {
+			console.error(colors.red('  No input received from stdin'))
+			process.exit(1)
+		}
+
+		console.log(colors.dim(`  Piped input: ${pipedInput.length} chars`))
+		await coder.ask(pipedInput)
+		process.exit(0)
+	}
+
+	// ── Banner ─────────────────────────────────────────────────────────────
+	console.log()
+	console.log(ui.banner('CODE', { font: 'Small', colors: ['cyan', 'blue'] }))
+
+	const toolCount = Object.keys(coder.tools).length
+	const allowCount = Object.values(permissions).filter(v => v === 'allow').length
+	const askCount = Object.values(permissions).filter(v => v === 'ask').length
+	const denyCount = Object.values(permissions).filter(v => v === 'deny').length
+	const loadedSkills = coder.state.get('loadedSkills') as string[]
+
+	console.log(colors.dim(`  ${toolCount} tools loaded`))
+	console.log(
+		colors.green(`  ${allowCount} allow`) + colors.dim(' · ') +
+		colors.yellow(`${askCount} ask`) + colors.dim(' · ') +
+		colors.red(`${denyCount} deny`)
+	)
+	if (loadedSkills.length) {
+		console.log(colors.dim(`  Skills: ${loadedSkills.join(', ')}`))
+	}
+	console.log()
+	console.log(colors.dim('  Commands: .exit  .perms  .skills  .allow <tool>  .deny <tool>  .gate <tool>  .allow-all  /console'))
+	console.log()
+
+	// ── Main loop ──────────────────────────────────────────────────────────
+	while (true) {
+		const input = await prompt()
+		if (!input) continue
+
+		// Meta commands
+		if (input === '.exit') break
+
+		if (input === '.perms') {
+			const perms = coder.permissions
+			const def = coder.state.get('defaultPermission')
+			console.log()
+			console.log(colors.dim(`  Default: ${def}`))
+			for (const [name, level] of Object.entries(perms).sort()) {
+				const color = level === 'allow' ? colors.green : level === 'deny' ? colors.red : colors.yellow
+				console.log(`  ${color(level.padEnd(5))} ${name}`)
+			}
+			console.log()
+			continue
+		}
+
+		if (input === '.skills') {
+			const skillsLib = container.feature('skillsLibrary')
+			if (!skillsLib.isStarted) await skillsLib.start()
+			const available = skillsLib.list()
+			const loaded = coder.state.get('loadedSkills') as string[]
+			console.log()
+			if (available.length === 0) {
+				console.log(colors.dim('  No skills found'))
+			} else {
+				for (const skill of available) {
+					const isLoaded = loaded.includes(skill.name)
+					const marker = isLoaded ? colors.green('●') : colors.dim('○')
+					console.log(`  ${marker} ${colors.bold(skill.name)} ${colors.dim('—')} ${colors.dim(skill.description || '')}`)
+				}
+				console.log()
+				console.log(colors.dim(`  ${loaded.length} loaded into context, ${available.length} total available`))
+			}
+			console.log()
+			continue
+		}
+
+		if (input.startsWith('.allow-all')) {
+			for (const t of Object.keys(coder.tools)) {
+				coder.permitTool(t)
+			}
+			console.log(colors.green('  All tools set to allow'))
+			continue
+		}
+
+		if (input.startsWith('.allow ')) {
+			const tool = input.slice(7).trim()
+			coder.permitTool(tool)
+			console.log(colors.green(`  ${tool} → allow`))
+			continue
+		}
+
+		if (input.startsWith('.deny ')) {
+			const tool = input.slice(6).trim()
+			coder.blockTool(tool)
+			console.log(colors.red(`  ${tool} → deny`))
+			continue
+		}
+
+		if (input.startsWith('.gate ')) {
+			const tool = input.slice(6).trim()
+			coder.gateTool(tool)
+			console.log(colors.yellow(`  ${tool} → ask`))
+			continue
+		}
+
+		if (input === '/console') {
+			// Pause readline so the REPL can own stdin
+			rl.close()
+
+			const featureContext: Record<string, any> = {}
+			for (const fname of container.features.available) {
+				try { featureContext[fname] = container.feature(fname) } catch {}
+			}
+
+			const replPrompt = ui.colors.magenta('console') + ui.colors.dim(' > ')
+			const repl = container.feature('repl', { prompt: replPrompt })
+
+			console.log()
+			console.log(colors.dim('  Dropping into console. The coder is available as `coder`.'))
+			console.log(colors.dim('  Type .exit to return to code.'))
+			console.log()
+
+			await repl.start({
+				context: {
+					...featureContext,
+					coder,
+					console,
+					setTimeout, setInterval, clearTimeout, clearInterval,
+					fetch,
+				},
+			})
+
+			// Wait for the REPL to close
+			await new Promise<void>((resolve) => {
+				repl._rl!.on('close', resolve)
+			})
+
+			// Resume readline
+			console.log()
+			console.log(colors.dim('  Back in code mode.'))
+			rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+			rlClosed = false
+			rl.on('close', () => { rlClosed = true })
+			continue
+		}
+
+		// Ask the coder
+		await coder.ask(input)
+	}
+
+	rl.close()
+	console.log()
+}
+
+commands.registerHandler('code', {
+	description: 'Autonomous coding assistant with file tools, bash, and permission gating',
+	argsSchema,
+	handler: code,
+})

package/src/commands/describe.ts

@@ -163,7 +163,12 @@ export default async function describe(options: z.infer<typeof argsSchema>, cont
 
 	if (wantsTypeScript) {
 		const output = renderResultAsTypeScript(result, targets, describer, sections)
-		console.log(output)
+		if (options.pretty) {
+			const ui = container.feature('ui')
+			console.log(ui.markdown('```ts\n' + output + '\n```'))
+		} else {
+			console.log(output)
+		}
 	} else if (options.json) {
 		console.log(JSON.stringify(result.json, null, 2))
 	} else if (options.pretty) {
@@ -192,7 +197,7 @@ function renderResultAsTypeScript(result: { json: any; text: string }, targets:
 	// Container introspection (has className, registries, factories)
 	if (json && json.className && json.registries) {
 		const container = (describer as any).container
-		return container.inspectAsType()
+		return container.introspectAsType()
 	}
 
 	// Array of results (e.g. from registry describe or multiple targets)

package/src/commands/index.ts

@@ -16,3 +16,4 @@ import './introspect.js'
 import './save-api-docs.js'
 import './bootstrap.js'
 import './select.js'
+import './code.js'

package/src/commands/sandbox-mcp.ts

@@ -140,7 +140,7 @@ export default async function mcpSandbox(options: z.infer<typeof argsSchema>, co
 			'  container.commands.available    — list available command names',
 			'  container.features.describe(n)  — get docs for a feature by name',
 			'  container.clients.describe(n)   — get docs for a client by name',
-			'  container.inspectAsText()       — full container introspection',
+			'  container.introspectAsText()       — full container introspection',
 			'  fs.readFile(path)               — read a file',
 			'  fs.readdir(dir)                 — list directory contents',
 			'  proc.exec(cmd)                  — run a shell command',
@@ -208,7 +208,7 @@ export default async function mcpSandbox(options: z.infer<typeof argsSchema>, co
 				.describe('Optional section to filter to. Omit for full overview.'),
 		}),
 		handler: (args) => {
-			return container.inspectAsText(args.section)
+			return container.introspectAsText(args.section)
 		},
 	})
 
@@ -340,9 +340,9 @@ export default async function mcpSandbox(options: z.infer<typeof argsSchema>, co
 				'container.features.describe("fs")      // Docs for the fs feature',
 				'container.features.describe("vm")      // Docs for the vm feature',
 				'container.clients.describe("rest")     // Docs for the rest client',
-				'container.inspectAsText()              // Full container introspection',
-				'container.inspectAsText("methods")     // Just the methods section',
-				'container.inspectAsText("state")       // Just the state section',
+				'container.introspectAsText()              // Full container introspection',
+				'container.introspectAsText("methods")     // Just the methods section',
+				'container.introspectAsText("state")       // Just the state section',
 				'```',
 				'',
 				'### Using features directly',
@@ -375,7 +375,7 @@ export default async function mcpSandbox(options: z.infer<typeof argsSchema>, co
 	mcpServer.prompt('introspect', {
 		description: 'Get full introspection of the Luca container — all registries, state, methods, events, and environment info.',
 		handler: async () => {
-			const text = container.inspectAsText()
+			const text = container.introspectAsText()
 			return [{
 				role: 'user' as const,
 				content: `Here is the full container introspection:\n\n${text}`,
@@ -388,7 +388,7 @@ export default async function mcpSandbox(options: z.infer<typeof argsSchema>, co
 		name: 'Container Info',
 		description: 'Full introspection of the running Luca container',
 		mimeType: 'text/markdown',
-		handler: () => container.inspectAsText(),
+		handler: () => container.introspectAsText(),
 	})
 
 	// --- Resource: feature list ---

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

@@ -24,7 +24,7 @@ export async function apiDocs(options: z.infer<typeof argsSchema>, context: Cont
 
 	const mkPath = (...args) => container.paths.resolve(outputFolder, ...args)
 
-	const result = await container.fs.writeFileAsync(mkPath('agi-container.md'), container.inspectAsText())
+	const result = await container.fs.writeFileAsync(mkPath('agi-container.md'), container.introspectAsText())
 
 	for(let reg of ['features','clients','servers']) {
 		const helperIds = container[reg].available

package/src/container-describer.ts

@@ -531,11 +531,11 @@ export class ContainerDescriber {
 		const container = this.container
 
 		if (sections.length === 0) {
-			const data = container.inspect()
-			return { json: data, text: container.inspectAsText(undefined, headingDepth) }
+			const data = container.introspect()
+			return { json: data, text: container.introspectAsText(undefined, headingDepth) }
 		}
 
-		const data = container.inspect()
+		const data = container.introspect()
 		const introspectionSections = sections.filter((s): s is IntrospectionSection => s !== 'description')
 		const textParts: string[] = []
 		const jsonResult: Record<string, any> = {}
@@ -552,7 +552,7 @@ export class ContainerDescriber {
 		}
 
 		for (const section of introspectionSections) {
-			textParts.push(container.inspectAsText(section, headingDepth))
+			textParts.push(container.introspectAsText(section, headingDepth))
 			jsonResult[section] = data[section]
 		}