@soederpop/luca 0.0.2

package/docs/philosophy.md

@@ -0,0 +1,85 @@
+# Luca's Philosophy
+
+> LUCA - Lightweight Universal Conversational Architecture
+
+If you open up a Developer console on a blank HTML page, you have the `window` object and the `document` object, and from those objects you have everything you need to build every web application you've ever interacted with, IN THEORY, without ever reloading the page.
+
+Obviously nobody builds applications this way in a single REPL, but in 2026 developers are people and Agent AIs collaborating on the same codebase in a bigger Read, Eval, Print, Loop that takes place across more computers and brains.
+
+Luca aims to provide a `container` object that gets you 60% of the way there before you write a line of application code. As the types of applications you build and who you build them for further narrow, the container grows to cover 95%.
+
+How? By layering, the way you layer dockerfiles. The things which change least frequently are solved once and cached. The things which change more frequently live in their own isolated layer. That loop is smaller, quicker — the difference between a dockerfile that reinstalls the OS every time you change the HTML file, and one that doesn't.
+
+## The Layer Model
+
+Think of it like docker layers:
+
+**Layer 1: Platform** — `NodeContainer`, `WebContainer`. Features that are universally applicable to any application in that runtime. Filesystem, networking, process management, event buses, observable state. You solve this once.
+
+**Layer 2: Domain** — `AGIContainer`, or imagine a `RestaurantContainer`, `FinanceContainer`. Features, clients, servers specific to that category of application. You solve this rarely.
+
+**Layer 3: The Actual Work** — The specific thing you're building for the specific person who needs it. This is what changes every day.
+
+Layer 1 and Layer 2 you solve once and almost never again. When you get to Layer 3, everything is so specific that it changes constantly. The entire point is to spend all of your energy on Layer 3. If you fix something in Layer 1, every project that uses it benefits immediately — just like every docker image based on alpine benefits when alpine patches something.
+
+The `container` is the central piece. You build it in layers with components that are stable enough to be reused across tasks, use cases, projects, and clients. And since it's JavaScript, it works in the browser or the server. Build a GitHub client in one project, add it to the container, start a brand new project with that same container, and the GitHub client is already there.
+
+## Helpers and Registries: Conversational Dependency Injection
+
+The `container` provides `Registries` of `Helpers`. A `Helper` is a formal, consistent interface for a category of thing. Features can be enabled. Servers can be started and stopped. Clients can be connected. Commands can be run. These "things" share common lifecycles (state) and emit similar events (started, connected, enabled). Clients, servers, features are part of almost every application I've built for 20 years, but every domain has its own categories too — Helpers can be customized to represent those.
+
+`Registries` are a central place for storing the various implementations and being able to discover which ones are available.
+
+The `container` provides factory functions — `feature()`, `server()`, `client()` — to create instances. Every helper instance has its own event bus, its own observable state, can be `introspected()` at runtime, and has fully typed interfaces that light up your IDE.
+
+## Why "Conversational"?
+
+The name means two things at once.
+
+First, you can literally talk to the container. Give an LLM access to the container object and tool calls, and it can discover what's available, learn how to use it, and build with it — all at runtime. The introspection system means nothing is hidden. Every feature, every method signature, every event, every state shape is discoverable programmatically.
+
+Second, the components talk to each other. Observable state, event buses, and well-documented typed interfaces mean that everything in the system can react to everything else through formal, predictable channels. Not magic strings and implicit coupling — actual typed contracts with build-time autocomplete and runtime introspection of the same.
+
+## A Shared Mental Model
+
+This is the real thesis.
+
+The human and the AI share the same mental model of how the code should be organized and structured. The human isn't just directing the AI — they're collaborating inside the same architecture, speaking the same language about the same things.
+
+A human defines the Helper — the interface, the lifecycle, the state shape, the events it emits. They decide *what* a thing is, *how* it behaves from the outside, and *where* it lives in the system. The AI understands that same structure and works within it. When the human says "make a client for Stripe," the AI already knows what a Client is, where it goes, what interface it needs to satisfy, and what lifecycle it follows. They're not negotiating from scratch every time — they're both operating from the same map.
+
+This matters because as AI builds more and more of the internals, the human still feels at home. The organization of the code is still theirs. The names are theirs. The architecture is theirs. The folder structure, the class hierarchy, the way things relate to each other — that's their map, and the AI respects it because the AI shares it.
+
+Defining Helpers is how a human says "in my world, these are the categories of things that exist, and this is how they work." The AI doesn't need to understand *why* those categories make sense for the business or the domain — it just needs the interface contract and it can implement anything that satisfies it.
+
+## Trust Through Composition
+
+Here's where it gets really interesting.
+
+Because everything is captured as Helpers with formal interfaces, every component can be reviewed, audited, and secured independently. You can track provenance — who wrote it, when, what it depends on. A Helper that's been vetted is a Helper you can trust.
+
+Over time, the AI generates less and less net-new code. Instead, it composes with existing Helpers — calling their interfaces, subscribing to their events, reading their state. The new code it does write gets captured into new Helpers that go through the same review cycle. The codebase becomes a growing library of trusted, audited building blocks.
+
+This flips the usual fear about AI-generated code on its head. Normally, the more an AI writes, the less confident you feel about what's in there. With Luca, the more an AI writes, the more it's using components you've already reviewed. The codebase gets *more* trustworthy as it grows, not less. The surface area of unreviewed code shrinks because the AI is reaching for existing Helpers instead of generating raw implementations from scratch every time.
+
+This also constrains the AI in a productive way. Instead of generating sprawling, unstructured code that the human has to reverse-engineer, the AI is given a clear place to put things and a clear shape they need to be. The result is a codebase that grows but stays navigable, because the human designed the map and the AI respects it.
+
+## The Agent Runtime
+
+Take this one step further.
+
+Imagine an Agent that already knows JavaScript like a master. Give it a `container` object. Through introspection alone, it can learn about every feature, server, client, and command available to it. It can discover their options, their observable state, the events they emit, and the signatures for all of these things. It can write code against them. It can modify itself at runtime. You can watch the thing being built, interact with it, steer it.
+
+This is not theoretical. The AGI container layer already does this — it wraps tools like Claude Code and OpenAI into the same Helper pattern, gives them the same observable state and event buses, and lets agents use the full container to build and extend themselves.
+
+The REPL-driven development style that Luca was originally designed for maps perfectly onto this. The same properties that make something nice to work with in a REPL — discoverability, introspection, observable state, immediate feedback — are exactly the properties that make something nice for an AI agent to work with.
+
+## Why This Architecture Specifically?
+
+Observable state, events, and well-documented APIs aren't arbitrary choices. They're specifically what makes things *conversational* in both senses:
+
+- **Observable state** means anything can watch anything else and react. Debugging, analytics, reporting, reactive UI patterns, data providers for React — all fall out naturally. An AI agent can monitor state to understand what's happening.
+- **Events** are the necessary primitive for JavaScript's async event loop, and they're also how components announce things to the rest of the system without needing to know who's listening. An AI agent can subscribe to events to understand what just happened.
+- **Introspection** means you never have to remember the specifics. You only need to know the philosophy, and the container will teach you the rest. This is true whether "you" is a human in a REPL or an AI agent with tool access.
+
+The fact that you can start from a single `container` object and learn everything it provides — how to interact with it, how to use it, what to expect from it — means the philosophy *is* the documentation. Know the pattern, and the system reveals itself.

package/docs/principles.md

@@ -0,0 +1,7 @@
+# Random Principles
+
+- I've built so many different client / server applications with JavaScript ( and many other languages ).  I've reinvented way too many things that could have been solved once.  The clearest example of this pain is a poorly structured dockerfile, e.g. one that reinstalls core os dependencies when you change an html file.
+
+- Nearly every application, I've structured as a "boss with liuetenants" so to speak, that everything else talked to.  The boss, the liuetenants, had some kind of state.  Events occur during their operations.  Sometimes these events need to be triggered.  Overtime, core patterns emerged, somewhat encouraged by popular frameworks in the shape they took or names I gave them.
+
+- In building Luca, we want to provide ways to ultimately narrow the range of possible outputs a first time developer, or AI assistant, might produce when asked to build something using a Luca `container` and its components.  The names themselves of the helpers, `clients`, `servers`, `features` already begin to describe their shape, purpose, where their code should live, etc. By going through the extra effort of building essentially a wrapper class, with descriptive interfaces, the developer will ultimately be delivering code that is easier to work with, and re-use in future efforts.

package/docs/prompts/audit-codebase-for-failures-to-use-the-container.md

@@ -0,0 +1,34 @@
+---
+reusable: true
+lastRanAt: 1772162827313
+durationMs: 278913
+outputTokens: 552
+---
+
+
+# Code Audit
+
+Do an audit of the code in the following folders:
+
+- src/**/features/**
+- src/**/clients/**
+- src/clients/**
+- src/servers/**
+- src/commands/**
+
+Ignore the fs, proc, git features in src/node/features.  These are a core abstraction that wraps the underlying ones provided by node or bun, so it is expected they would use child_process, fs, etc.  In general, if the feature you're looking at is intended to be wrapping a core runtime / os primitive, it is probably ok ( that's the point of the feature )
+
+if a completely unrelated feature is using the fs or path module, or Bun unguarded, then that's probably an issue.
+
+Look for instances of the following, but don't fix them yet.
+
+- using file system directly, instead of this.container.fs ( except the file system feature itself )
+- using the path module functions instead of this.container.paths.resolve ( with the exception of fileManager, where it is ok )
+- reinventing the wheel in general instead of using functionality already provided by the container
+- anything that would break compatibility with node.js instead of Bun.  make sure you wrap it in a guard (if this.container.isBun)
+
+Save the results of your audit in docs/reports/code-audit-results.md
+
+If this file already exists, read it first, and note cases where items persist.
+
+The next step will be me reviewing the audit, providing commentary, and advising you what to fix

package/docs/prompts/mcp-test-easy-command.md

@@ -0,0 +1,27 @@
+---
+target: claude
+reusable: true
+repeatable: true
+---
+
+# MCP Test: Build a Command
+
+You are in an empty luca project. The `luca` CLI is available and you have a `luca-sandbox` MCP server connected.
+
+## Task
+
+Create a luca command called `greet` in `commands/greet.ts` that:
+
+1. Accepts a `--name` flag (string, defaults to "world")
+2. Accepts a `--shout` flag (boolean, defaults to false)
+3. Prints "Hello, {name}!" to stdout
+4. If `--shout` is true, uppercases the entire message
+
+The command should be runnable via `luca greet --name Jon --shout`.
+
+## Rules
+
+- Do not install any npm packages
+- Import only from `@soederpop/luca`
+- Use the MCP tools to learn the command pattern before writing code
+- After creating the file, verify it works by running `luca greet --name Test`

package/docs/reports/assistant-bugs.md

@@ -0,0 +1,38 @@
+# Assistant systemPrompt Bug Fix Verification
+
+The bug: class field initializers (`private _systemPrompt: string = ''`) on Feature subclasses
+overwrite values set during `afterInitialize()` because ES2022 field initializers run AFTER `super()` returns.
+
+Fix: use `declare private _systemPrompt: string` which emits no JavaScript, so afterInitialize values persist.
+
+## Test
+
+```ts
+const assistant = container.feature('assistant', {
+  folder: '/Users/jon/@soederpop/commands/voice/assistant'
+})
+```
+
+systemPrompt should contain the CORE.md content (not be empty):
+
+```ts
+console.log("systemPrompt length:", assistant.systemPrompt.length)
+console.log("contains omar:", assistant.systemPrompt.toLowerCase().includes("omar"))
+console.log("first 80 chars:", assistant.systemPrompt.slice(0, 80))
+```
+
+Tools should have been loaded from tools.ts:
+
+```ts
+console.log("tools loaded:", Object.keys(assistant.tools))
+```
+
+Starting the assistant should pass the systemPrompt into the conversation:
+
+```ts
+await assistant.start()
+const systemMsg = assistant.conversation.messages[0]
+console.log("conversation has system message:", systemMsg.role === "system")
+console.log("system message has content:", systemMsg.content.length > 0)
+console.log("system message contains omar:", systemMsg.content.toLowerCase().includes("omar"))
+```

package/docs/reports/attach-pattern-usage.md

@@ -0,0 +1,18 @@
+# Attach Pattern
+
+Here is some problematic code:
+
+```ts skip
+const { container } = context
+const { VoiceRouter } = await import(resolve(import.meta.dir, 'voice/router.ts'))
+container.features.register('voiceRouter', VoiceRouter as any)
+const router = container.feature('voiceRouter' as any, { enable: true }) as InstanceType<typeof VoiceRouter>
+```
+
+I'd rather see
+
+```ts skip
+// we know since we're inside a command this has to be our path anyway, relative to the container's cwd is how we're discovered
+await import(container.paths.resolve('commands','voice','router.ts')).then(({ VoiceRouter }) => container.use(VoiceRouter))
+```
+

package/docs/reports/code-audit-results.md

@@ -0,0 +1,391 @@
+---
+title: Code Audit - Container Abstraction Violations
+status: active
+type: report
+createdAt: 2026-02-26
+updatedAt: 2026-02-26
+---
+
+# Code Audit: Container Abstraction Violations
+
+Audit of `src/**/features/**`, `src/**/clients/**`, `src/clients/**`, `src/servers/**`, and `src/commands/**` for violations of the container abstraction pattern.
+
+**Excluded from audit**: `fs.ts`, `proc.ts`, `git.ts`, `os.ts` — these are core wrappers that intentionally import Node builtins. `file-manager.ts` is allowed to use `path` directly.
+
+## Severity Legend
+
+- **HIGH**: Breaks Node.js compatibility, or completely bypasses container when equivalent exists
+- **MEDIUM**: Uses builtins/process.env when container provides an alternative
+- **LOW**: Minor style issue, or acceptable edge case
+
+---
+
+## Summary
+
+| Category | Files Audited | Files with Violations | HIGH | MEDIUM | LOW |
+|----------|--------------|----------------------|------|--------|-----|
+| Node Features | 14 | 11 | 19 | 14 | 6 |
+| AGI Features | 10 | 3 | 12 | 4 | 0 |
+| Clients | 7 | 3 | 3 | 2 | 0 |
+| Servers | 3 | 2 | 1 | 1 | 0 |
+| Commands | 11 | 5 | 3 | 5 | 2 |
+| **Total** | **45** | **24** | **38** | **26** | **8** |
+
+### Top Offenders (by violation count)
+
+1. **`skills-library.ts`** — 7 HIGH (imports `path`, `os`, `fs/promises` and uses throughout)
+2. **`claude-code.ts`** — 8 violations (3x `Bun.spawn`, 1x `Bun.write`, 2x dynamic `fs/promises`, 2x `process.env`)
+3. **`launcher-app-command-listener.ts`** — 7 HIGH (fs, path, os at module top-level)
+4. **`window-manager.ts`** — 7 HIGH (same pattern as launcher-app)
+5. **`python.ts`** — 9+ uses of `existsSync`/`join` from builtins
+6. **`package-finder.ts`** — 5 violations (partially migrated, inconsistent)
+7. **`comfyui/index.ts`** — 5 violations in one method (dynamic imports + `Bun.write`)
+8. **`openai-codex.ts`** — 4 violations (3x `Bun.spawn`, 2x `process.env`)
+
+### Bug Found
+
+**`repl.ts` lines 92, 192** — Uses `fs.readFileSync` and `fs.appendFileSync` but **never imports `fs`**. This will throw `ReferenceError` at runtime when history persistence is used.
+
+---
+
+## Detailed Findings
+
+### Node Features (`src/node/features/`)
+
+#### `package-finder.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 4 | `import { readdir, readFile } from 'fs/promises'` | `this.container.fs` | HIGH |
+| 5 | `import { resolve, join, basename } from 'path'` | `this.container.paths` | MEDIUM |
+| 242 | `readFile(path)` direct usage | `this.container.fs.readFileAsync()` | HIGH |
+| 471, 477 | `readdir(...)` direct usage | `this.container.fs.readdirAsync()` | HIGH |
+| 475, 477 | `join(...)` direct usage | `this.container.paths.join()` | MEDIUM |
+
+Note: Line 523 correctly uses `this.container.fs.findUpAsync` — file is partially migrated but inconsistent.
+
+#### `python.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 4 | `import { existsSync } from 'fs'` | `this.container.fs.exists()` | HIGH |
+| 5 | `import { join, resolve } from 'path'` | `this.container.paths` | MEDIUM |
+| 84 | `resolve(this.options.dir)` | `this.container.paths.resolve()` | MEDIUM |
+| 93, 145, 158, 171-172, 177, 245-246, 256, 259 | 9+ calls to `existsSync()` | `this.container.fs.exists()` | HIGH |
+| 145, 158, 171+ | `join(...)` throughout `detectEnvironment()` | `this.container.paths.join()` | MEDIUM |
+
+Note: `execute()` method (line 313+) correctly uses container features — only `detectEnvironment()` and `enable()` are violating.
+
+#### `launcher-app-command-listener.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 5 | `import { homedir } from 'os'` | `this.container.feature('os').homedir` | MEDIUM |
+| 6 | `import { join, dirname } from 'path'` | `this.container.paths` | MEDIUM |
+| 7 | `import { existsSync, unlinkSync, mkdirSync } from 'fs'` | `this.container.fs` | HIGH |
+| 9-15 | `homedir()`, `join(...)` at module top-level (before container exists) | Must defer to runtime (`enable()` or getter) | HIGH |
+| 250-253 | `dirname()`, `existsSync()`, `mkdirSync()` | `this.container.paths`/`this.container.fs` | HIGH |
+| 260-263 | `existsSync()`, `unlinkSync()` | `this.container.fs` | HIGH |
+| 307-308 | `existsSync()`, `unlinkSync()` | `this.container.fs` | HIGH |
+
+#### `window-manager.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 5 | `import { homedir } from 'os'` | `this.container.feature('os').homedir` | MEDIUM |
+| 6 | `import { join, dirname } from 'path'` | `this.container.paths` | MEDIUM |
+| 8 | `import { existsSync, unlinkSync, mkdirSync } from 'fs'` | `this.container.fs` | HIGH |
+| 10-16 | `homedir()`, `join(...)` at module top-level | Must defer to runtime | HIGH |
+| 354-372 | `dirname()`, `existsSync()`, `mkdirSync()`, `unlinkSync()` | Container equivalents | HIGH |
+| 420-421 | `existsSync()`, `unlinkSync()` | `this.container.fs` | HIGH |
+
+#### `helpers.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 11 | `import { resolve, parse } from 'path'` | `this.container.paths` | MEDIUM |
+| 134, 258 | `resolve(this.rootDir, ...)` | `this.container.paths.resolve()` | MEDIUM |
+| 324 | `const { Glob } = globalThis.Bun \|\| (await import('bun'))` — unguarded `Bun.Glob` | Guard with `this.container.isBun` or use container glob | HIGH |
+
+#### `tmux.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 479, 531 | `process.env.TMUX` | Container environment handling | MEDIUM |
+| 505-509 | `process.platform === 'darwin'` / `'linux'` | `this.container.feature('os').platform` | LOW |
+| 543-544 | `process.argv` direct access | Container equivalent | LOW |
+| 546 | `import('child_process')` then `execSync(...)` | `this.container.feature('proc')` | HIGH |
+
+#### `process-manager.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 104 | `ReturnType<typeof Bun.spawn>` — type depends on Bun | Runtime-agnostic type or guard | HIGH |
+| 164 | `Bun.spawn(...)` — unguarded | `this.container.feature('proc')` or guard with `isBun` | HIGH |
+| 166 | `{ ...process.env, ...spawnOptions.env }` | Container environment | MEDIUM |
+| 508-530 | `process.on('exit')`, `process.on('SIGINT')`, etc. | Container lifecycle hooks | MEDIUM |
+
+#### `google-auth.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 108, 115, 123, 147, 486 | `process.env.GOOGLE_*` (5 occurrences) | Container env handling (already declares `static envVars`) | MEDIUM |
+| 247 | `Bun.serve({...})` — unguarded | Guard with `isBun` or use container server | HIGH |
+
+#### `repl.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 92 | `fs.readFileSync(...)` — **`fs` is NOT imported** | `this.container.fs.readFileSync()` | **HIGH (BUG)** |
+| 172 | `Bun.inspect(result, ...)` — unguarded | Guard with `this.container.isBun` | MEDIUM |
+| 192 | `fs.appendFileSync(...)` — **`fs` is NOT imported** | `this.container.fs` | **HIGH (BUG)** |
+
+#### `tts.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 67 | `process.env.RUNPOD_API_KEY` | Container env handling | MEDIUM |
+
+Otherwise clean — correctly uses `this.container.paths`, `this.container.fs`, `this.container.feature('os')`.
+
+#### `downloader.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 3 | `import fetch from 'cross-fetch'` | Global `fetch` (available in Bun and Node 18+) or container REST client | HIGH |
+
+Otherwise clean — correctly uses `this.container.fs.writeFileAsync` and `this.container.paths.resolve`.
+
+#### `runpod.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 4 | `import axios from 'axios'` | `this.container.client('rest')` or global `fetch` | HIGH |
+| 46 | `process.env.RUNPOD_API_KEY` | Container env handling | MEDIUM |
+
+#### `telegram.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 97 | `process.env.TELEGRAM_BOT_TOKEN` | Container env handling | MEDIUM |
+
+Otherwise clean — properly uses `container.server('express')` and `container.feature('ui')`.
+
+---
+
+### AGI Features (`src/agi/features/`)
+
+#### `skills-library.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 2 | `import path from 'path'` | `this.container.paths` | HIGH |
+| 3 | `import os from 'os'` | `this.container.paths.homedir` or container os feature | HIGH |
+| 4 | `import fs from 'fs/promises'` | `this.container.fs` | HIGH |
+| 131 | `path.resolve(os.homedir(), '.luca', 'skills')` | `this.container.paths.resolve(...)` | HIGH |
+| 250 | `await fs.mkdir(..., { recursive: true })` | `this.container.fs.mkdirp()` or `ensureFolder()` | HIGH |
+| 330-331 | `path.resolve(...)` in `remove()` | `this.container.paths.resolve()` | HIGH |
+| 335 | `await fs.rm(skillDir, { recursive: true })` | `this.container.fs.rm()` | HIGH |
+
+Worst AGI offender — three Node builtin imports at top level used throughout.
+
+#### `claude-code.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 7 | `import type { Subprocess } from 'bun'` | Runtime-agnostic type | MEDIUM |
+| 275 | `Bun.spawn([this.claudePath, '--version'], ...)` | Container `proc` feature | HIGH |
+| 334 | `const { appendFile } = await import('node:fs/promises')` | `this.container.fs` | HIGH |
+| 382 | `process.env.TMPDIR` | Container temp dir handling | MEDIUM |
+| 384 | `await Bun.write(tmpPath, ...)` | Container fs write | HIGH |
+| 619-624 | `Bun.spawn(...)` + `{ ...process.env }` | Container `proc` + env | HIGH |
+| 750-755 | `Bun.spawn(...)` + `{ ...process.env }` | Same | HIGH |
+| 920 | `const { unlink } = await import('node:fs/promises')` | `this.container.fs` | HIGH |
+
+Completely Bun-locked. Three `Bun.spawn` call sites, one `Bun.write`, two dynamic `fs/promises` imports.
+
+#### `openai-codex.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 7 | `import type { Subprocess } from 'bun'` | Runtime-agnostic type | MEDIUM |
+| 174 | `Bun.spawn([this.codexPath, '--version'], ...)` | Container `proc` feature | HIGH |
+| 375-379 | `Bun.spawn(...)` + `{ ...process.env }` | Container `proc` + env | HIGH |
+| 502-507 | `Bun.spawn(...)` + `{ ...process.env }` | Same | HIGH |
+
+Same pattern as `claude-code.ts`.
+
+#### Clean AGI Files
+
+- `conversation.ts` — Clean
+- `conversation-history.ts` — Clean (uses `container.feature('diskCache')`)
+- `assistant.ts` — Exemplary (uses `container.fs`, `container.paths`, `container.feature('vm')`)
+- `assistants-manager.ts` — Clean (uses `container.paths`, `container.fs`)
+- `docs-reader.ts` — Clean
+- `openapi.ts` — Clean (uses global `fetch`)
+- `heartbeat.ts` — Clean (uses `container.feature('proc')`, `container.feature('vm')`, etc.)
+
+---
+
+### Clients (`src/clients/`, `src/web/clients/`)
+
+#### `comfyui/index.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 531 | `const { mkdir } = await import("fs/promises")` | `this.container.fs.ensureFolder()` | HIGH |
+| 532 | `const { join } = await import("path")` | `this.container.paths.join()` | MEDIUM |
+| 533 | `await mkdir(options.outputDir, { recursive: true })` | `this.container.fs.ensureFolder()` | HIGH |
+| 537 | `const localPath = join(...)` | `this.container.paths.join()` | MEDIUM |
+| 538 | `await Bun.write(localPath, buf)` — unguarded | `this.container.fs.writeFileAsync()` | HIGH |
+
+All 5 violations are in the `runWorkflow` method (lines 530-541).
+
+#### `openai/index.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 76 | `process.env.OPENAI_API_KEY` | Container env (already declares `static envVars`) | MEDIUM |
+
+#### `elevenlabs/index.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 100 | `process.env.ELEVENLABS_API_KEY` | Container env (already declares `static envVars`) | MEDIUM |
+
+#### Clean Client Files
+
+- `civitai/index.ts` — Exemplary (uses `container.fs`, `container.paths`, `container.feature("downloader")`)
+- `supabase/index.ts` — Clean
+- `client-template.ts` — Clean
+- `web/clients/socket.ts` — Clean
+
+---
+
+### Servers (`src/servers/`)
+
+#### `express.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 123 | `new Bun.Glob('**/*.ts')` — unguarded | Container glob/fs.walk or guard with `isBun` | HIGH |
+
+The entire `useEndpoints` method (lines 123-146) depends on `Bun.Glob`.
+
+#### `mcp.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 440 | `const { randomUUID } = await import('node:crypto')` | `crypto.randomUUID()` (global Web Crypto) or `this.container.utils.uuid()` | MEDIUM |
+
+#### Clean Server Files
+
+- `socket.ts` — Clean
+
+---
+
+### Commands (`src/commands/`)
+
+#### `prompt.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 250 | `await Bun.write(resolvedPath, updated)` — unguarded | `container.fs.writeFileAsync()` (already destructures `fs` on line 205!) | HIGH |
+| 256 | `await Bun.write(outPath, markdown)` — unguarded | `container.fs.writeFileAsync()` | HIGH |
+| 85, 88, 118, 147-179 | Extensive `process.stdout.write()` for streaming | Container `ui` feature | MEDIUM |
+
+Inconsistent — lines 205+ use `container.fs` properly, but lines 250/256 use `Bun.write`.
+
+#### `chat.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 2 | `import * as readline from 'readline'` | Container `repl` feature or `ui.askQuestion()` | HIGH |
+| 94-97 | `readline.createInterface({ input: process.stdin, output: process.stdout })` | Container input abstraction | HIGH |
+| 68-69, 76, 81, 86, 90 | `process.stdout.write(...)` | Container `ui` feature | MEDIUM |
+
+The `console` command demonstrates the correct pattern using `container.feature('repl')`.
+
+#### `console.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 67 | `Bun` injected into REPL context without guard | Guard with `container.isBun` | MEDIUM |
+
+#### `sandbox-mcp.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 42 | `Bun` injected into VM context without guard | Guard with `container.isBun` | MEDIUM |
+
+#### `run.ts`
+
+| Line(s) | Violation | Should Use | Severity |
+|---------|-----------|-----------|----------|
+| 218 | `Bun` injected into REPL context without guard | Guard with `container.isBun` | MEDIUM |
+
+#### Clean Command Files
+
+- `eval.ts` — Clean
+- `describe.ts` — Exemplary
+- `help.ts` — Clean
+- `index.ts` — Clean (barrel file)
+- `serve.ts` — Clean (uses container throughout)
+- `mcp.ts` — Clean
+
+---
+
+## Recurring Patterns
+
+### 1. `process.env` for API Keys (MEDIUM, 10+ files)
+Many features/clients declare `static envVars = [...]` but then read `process.env.KEY` directly in getters. The container should mediate this. Affected: `google-auth.ts`, `tts.ts`, `runpod.ts`, `telegram.ts`, `openai/index.ts`, `elevenlabs/index.ts`.
+
+### 2. Unguarded `Bun.spawn` (HIGH, 5 files)
+`claude-code.ts`, `openai-codex.ts`, `process-manager.ts` all call `Bun.spawn` without checking `container.isBun`. These need either proc feature usage or runtime guards.
+
+### 3. Unguarded `Bun.write` (HIGH, 3 files)
+`prompt.ts`, `claude-code.ts`, `comfyui/index.ts` use `Bun.write` when `container.fs.writeFileAsync()` is available.
+
+### 4. Module-level `homedir()`/`join()` (HIGH, 2 files)
+`launcher-app-command-listener.ts` and `window-manager.ts` compute paths at import time using `os.homedir()` and `path.join()`, before any container exists. These must be deferred to `enable()` or computed lazily.
+
+### 5. Third-party HTTP imports (HIGH, 2 files)
+`downloader.ts` imports `cross-fetch` and `runpod.ts` imports `axios` when global `fetch` and `container.client('rest')` are available.
+
+### 6. Unguarded `Bun.Glob` (HIGH, 2 files)
+`helpers.ts` and `express.ts` use `Bun.Glob` without runtime guards. The container's fs feature provides glob/walk capabilities.
+
+---
+
+## Recommended Fix Priority
+
+### Priority 1 — Bugs
+- [ ] `repl.ts` — Fix missing `fs` import (lines 92, 192). Use `this.container.fs` instead.
+
+### Priority 2 — Bun-only code (breaks Node compatibility)
+- [ ] `claude-code.ts` — Replace `Bun.spawn` with proc feature or add `isBun` guards
+- [ ] `openai-codex.ts` — Same pattern as claude-code
+- [ ] `process-manager.ts` — Replace `Bun.spawn` with proc feature or guard
+- [ ] `google-auth.ts` — Replace `Bun.serve` with guard or container server
+- [ ] `express.ts` — Replace `Bun.Glob` with container glob or guard
+- [ ] `helpers.ts` — Replace `Bun.Glob` with container glob or guard
+- [ ] `prompt.ts` — Replace `Bun.write` with `container.fs.writeFileAsync`
+- [ ] `comfyui/index.ts` — Replace `Bun.write` + dynamic imports with container equivalents
+
+### Priority 3 — Direct builtin imports (bypasses container)
+- [ ] `skills-library.ts` — Replace all `path`, `os`, `fs/promises` with container equivalents
+- [ ] `package-finder.ts` — Complete migration to container fs/paths
+- [ ] `python.ts` — Replace `existsSync`/`join` with container equivalents
+- [ ] `launcher-app-command-listener.ts` — Replace fs/path/os with container, defer module-level computations
+- [ ] `window-manager.ts` — Same as launcher-app
+- [ ] `downloader.ts` — Remove `cross-fetch`, use global `fetch`
+- [ ] `runpod.ts` — Remove `axios`, use global `fetch` or container REST client
+- [ ] `chat.ts` — Replace `readline` with container `repl` feature
+
+### Priority 4 — `process.env` standardization
+- [ ] Create or document a standard pattern for env var access across features/clients
+- [ ] Update `google-auth.ts`, `tts.ts`, `runpod.ts`, `telegram.ts`, `openai/index.ts`, `elevenlabs/index.ts`
+
+### Priority 5 — Minor guards
+- [ ] `console.ts`, `sandbox-mcp.ts`, `run.ts` — Guard `Bun` global injection with `container.isBun`
+- [ ] `tmux.ts` — Replace `execSync` dynamic import with `container.feature('proc')`