luca 3.0.0 → 3.1.0

package/.github/workflows/release.yaml

@@ -113,6 +113,7 @@ jobs:
         run: |
           codesign --sign "Developer ID Application: Demitra Del Fiacco (77WL45HR8M)" \
             --force --options runtime --timestamp dist/release/luca-darwin-x64
+          codesign --remove-signature dist/release/luca-darwin-arm64
           codesign --sign "Developer ID Application: Demitra Del Fiacco (77WL45HR8M)" \
             --force --options runtime --timestamp dist/release/luca-darwin-arm64
 

package/CLAUDE.md

@@ -14,20 +14,28 @@ The `container` and its helpers are perfect for scripts and long running service
 
 On the frontend the browser container is perfect for highly reactive, stateful web applications, especially works well with React.
 
+## Developer Standards
+
+- Please try not to have broken tests committed to the build and let them slide.  Encourage me to fix them so they dont grow out of control.
+- When working on features, clients, servers, or other helpers, the introspection system relies on good zod descriptions, and good jsdoc descriptions
+
+
 ## The `luca` CLI
 
 - in dev, `bun run src/cli/cli.ts` is the same as `luca`
 
 - in prod, or educational material, `luca` refers to the binary build.  In this mode, it can work in any project, and load `commands/` and `endpoints/` through its VM and therefore allows folders of these modules which don't depend on anything from NPM to extend the CLI and be used in commands like `luca serve` to run a local express server
 
-- The `luca` cli is an extremely helpful tool.  
-	- it runs code `luca eval "container.features.available"` 
+- The `luca` cli is an extremely helpful tool.
+	- it runs code `luca eval "container.features.available"`
 	- it generates docs:
 		- `luca describe diskCache`
 		- `luca describe` describe the container itself
 		- `luca describe servers` describe which servers are available
 		- `luca describe ui.banner` describe a specific method or getter on a helper
 		- the arguments to describe are pretty forgiving and permissive
+	- `luca chat` — start an interactive chat session with an assistant
+	- `luca scaffold assistant <name>` — generate boilerplate for a new assistant
 
 **IMPORTANT NOTE** When trying to investigate features, clients, servers, etc, see if these tools can help you first instead of searching for files and reading them that way.  If youw ant to understand what they do, vs how theyre actually implemented
 

package/README.md

@@ -1,26 +1,33 @@
 # Luca
 
 **Lightweight Universal Conversational Architecture**
+*(aka Le Ultimate Component Architecture)*
 
-A single binary CLI that ships 40+ self-documenting features, clients, and servers. No `npm install`, no setup — download it and start building.
+An agent-native TypeScript runtime that ships as a single binary — and builds yours too.
 
-Luca gives you a `container` object — think of it like a Docker container for your application runtime. It's a per-process singleton, event bus, state machine, and dependency injector all in one. Layer your own features, clients, servers, commands, and endpoints on top of the base `NodeContainer` (server) or `WebContainer` (browser), then bundle it into your own single-file executable or browser build.
+Luca gives humans and AI agents the same architectural map: one self-documenting `container` object with typed features, clients, servers, commands, state, events, and runtime docs. The agent doesn't guess at architecture — it discovers it. No `npm install`, no `node_modules`, no supply chain exposure, no ceremony.
 
-The `AGIContainer` extends the node stack with features, clients, and servers for building AI assistants — wrappers around major coding models, tool orchestration, and UIs to visualize them working.
+## What Makes Luca Different
 
-## Installation
+AI agents today either generate sprawling ad-hoc code or fight against frameworks that weren't designed for them. They don't know what's available, what conventions to follow, or where to put things. The result is brittle, unreviewable output that drifts further from the codebase with every generation.
+
+Luca solves this with three ideas:
+
+**One introspectable container.** Every Luca app has a single `container` — a dependency-injected runtime that carries features, clients, servers, commands, endpoints, observable state, and an event bus. Every component describes itself: constructor options, method signatures, events emitted, state shape. The human reads the same docs the agent reads. There is one way to do things.
 
-### Quick install (macOS/Linux)
+**Single binary in, single binary out.** Luca ships as a standalone binary. No runtime dependencies, no package manager, no exposure to the npm supply chain. You use it to build your project, then compile your project into its own standalone binary with your custom commands, features, endpoints, and assistants baked in.
+
+**The assistant is a first-class citizen.** Luca's `Assistant` class can `use()` any feature, client, or server in the container — inheriting its tools automatically. The assistant doesn't need hand-written tool definitions. It discovers capabilities from the runtime it's embedded in.
+
+## Installation
 
 ```sh
 curl -fsSL https://luca-js.soederpop.com/install.sh | bash
 ```
 
-This detects your platform, downloads the right binary, and puts `luca` in your path. Done.
+Detects your platform, downloads the binary, puts `luca` in your path. Done.
 
-### Manual download
-
-Grab the latest release for your platform from [GitHub Releases](https://github.com/soederpop/luca/releases/latest):
+Or grab a release directly from [GitHub Releases](https://github.com/soederpop/luca/releases/latest):
 
 | Platform | Binary |
 |----------|--------|
@@ -30,137 +37,149 @@ Grab the latest release for your platform from [GitHub Releases](https://github.
 | Linux ARM64 | `luca-linux-arm64` |
 | Windows x64 | `luca-windows-x64.exe` |
 
-### Verify
-
 ```sh
 luca --version
-# luca v0.0.34 (main@325a0ee) built 2026-03-25T06:10:28Z
 ```
 
 ## Quick Start
 
-### Bootstrap a new project
-
 ```sh
 luca bootstrap my-app
 cd my-app
 ```
 
-Or just run `luca bootstrap` and it'll ask you for a project name. This scaffolds a project with `commands/`, `endpoints/`, `features/`, `docs/`, and AI assistant configuration — everything wired up and ready to extend.
+This scaffolds a project with `commands/`, `endpoints/`, `features/`, `docs/`, and AI assistant configuration — everything wired up and ready to extend.
 
-### Explore
+Now explore what the runtime can do:
 
 ```sh
 luca                              # list all commands
-luca describe features            # index of 40+ features
-luca describe fs                  # full docs for any feature
+luca describe features            # see every available feature
+luca describe fs                  # full docs for a specific feature
 luca describe fs.readFile         # drill into a specific method
-luca eval "container.features.available"  # run code with the container in scope
+luca eval "container.features.available"  # run code against the live container
 luca console                      # full REPL
 ```
 
-### Run scripts and markdown
+This is the core loop: discover what's available, evaluate code against it, build on top of it. Your AI assistant does the same thing.
 
-`luca run` executes TypeScript, JavaScript, and markdown files. Markdown files have their code blocks executed in order, with `container` already in scope — no imports needed:
+## The Container
 
-````md
-# my-script.md
-
-Grab some data and print it:
+One import. One object. Everything on it.
 
 ```ts
-const fs = container.feature('fs')
-const files = await fs.readdir('.')
-console.log(`Found ${files.length} files`)
+import container from 'luca'
+
+container.features.available   // ['fs', 'git', 'proc', 'vault', 'yaml', 'sqlite', ...]
+container.clients.available    // ['rest', 'websocket', ...]
+container.servers.available    // ['express', 'websocket', 'ipc', 'mcp', ...]
 ```
 
-Then do something with it:
+The container is a singleton — a per-process global that acts as dependency injector, event bus, and state machine. Features, clients, and servers are lazy-loaded from registries. Every helper carries introspection metadata that powers `luca describe`, the REPL, and agent tool discovery.
 
 ```ts
-const yaml = container.feature('yaml')
-console.log(yaml.stringify({ files }))
-```
-````
-
-```sh
-luca run my-script.md
+const fs = container.feature('fs')
+const rest = container.client('rest', { baseURL: 'https://api.example.com' })
+const server = container.server('express')
 ```
 
-Each block shares state with the previous ones, so variables defined in one block are available in the next. Use `--safe` to require approval before each block, or `--console` to drop into a REPL afterward with all the accumulated context.  **Note:** if your block uses top-level awaits, we can't preserve context.  You can use `container.addContext({ yourVariable })` and it will be available as a global variable in future blocks.
+No imports beyond the container. No `require('fs')`, no `import axios`, no `npm install anything`. The container provides file I/O, HTTP clients, databases, YAML parsing, git operations, browser automation, terminal UI, semantic search, encryption, and more — all typed, all documented, all discoverable at runtime.
 
-### Serve
+### In the browser
 
-```sh
-luca serve   # serves endpoints/ folder as HTTP routes
+```js
+import container from 'https://esm.sh/luca/web'
 ```
 
-See [`docs/CLI.md`](./docs/CLI.md) for the full CLI reference.
+Same singleton pattern, optimized for browser features. `window.luca` is set automatically.
 
-## Importing the container into your own scripts / modules
+## Build an Assistant
 
-```ts
-import container from '@soederpop/luca'
-```
-
-That's it — you get one object with everything on it. No factory function, no setup. It's a singleton.
+The assistant is the interface that ties everything together. It can `use()` any module in the container, automatically inheriting that module's tools:
 
-We do export the framework classes (`WebContainer`, `Feature`, `Client`, `Server`, etc.) if you want to extend them, but for using the system you only ever need the default export.
-
-### In the browser via esm.sh
+```ts
+import container from 'luca'
 
-**Static import:**
+const browser = container.feature('browserUse', { headed: true })
+const assistant = container.feature('assistant', {
+  systemPrompt: 'You are a web research assistant.',
+  model: 'gpt-4.1-mini',
+})
 
-```js
-import container from 'https://esm.sh/@soederpop/luca/web'
+// browserUse injects its tools — open, click, type, screenshot, extract, etc.
+assistant.use(browser)
+await assistant.start()
 
-container.features.available  // ['fetch', 'state', 'ui', ...]
+await assistant.ask('Go to hacker news and tell me the top 3 stories')
 ```
 
-**Dynamic import:**
+The assistant doesn't need hand-written tool schemas. When it calls `use(browser)`, it gets every tool that `browserUse` exposes — typed, documented, ready to invoke. Swap `browserUse` for `fs` or `git` or `sqlite` and the assistant gets a completely different toolkit from the same pattern.
 
-```js
-const { default: container } = await import('https://esm.sh/@soederpop/luca/web')
+This is what agent-native means: the runtime teaches the agent what it can do.
 
-container.features.available  // same singleton
-```
+### The Assistant as Operator
 
-With dynamic import you have to pick it off `default` yourself — there's no top-level default binding like the static form gives you. Either way, it's the same singleton container, and `window.luca` is set automatically so you can poke at it from the console.
+Most agent frameworks give you a chat loop with tool calls bolted on. Luca gives you an agent that can operate real infrastructure.
 
-## How It Works
+The container has servers — REST, WebSocket, IPC. It has clients for all of them. It has process management, a VM, file I/O, databases, git, docker, SSH, even GPU compute over RunPod. The assistant can `use()` any combination of these, which means you can build agents that:
 
-### Self-documenting at runtime
+- **Stand up and manage servers** — spin up an Express server, add routes, react to incoming requests
+- **Listen to events across transports** — WebSocket messages, IPC signals, HTTP webhooks, file system changes
+- **Spawn and manage processes** — launch child processes, monitor their output, kill them when done — locally, over SSH, in Docker containers, or on remote GPU instances
+- **Inspect and react to state** — every helper has observable state and an event bus; the assistant can watch for changes and act on them autonomously
+- **Run code in a sandboxed VM** — execute untrusted code safely, evaluate expressions, build REPL-like workflows
 
-Every helper (feature, client, server) carries its own introspection metadata — constructor options, observable state shape, events emitted, environment variables used, method signatures. This powers `luca describe`, works in the REPL, and enables metaprogramming.
+The assistant isn't answering questions in a chat window. It's running your infrastructure, reacting to events in real time, and coordinating across multiple systems — all through the same `container` it already knows how to discover.
 
 ```ts
-import container from '@soederpop/luca'
+const assistant = container.feature('assistant', {
+  systemPrompt: 'You manage the deployment pipeline. Monitor builds, restart failed services, report status.',
+  model: 'gpt-4.1-mini',
+})
 
-container.features.available   // ['fs','git','proc','vault',...]
-container.clients.available    // ['rest','websocket']
-container.servers.available    // ['express','websocket','ipc','mcp']
+assistant.use(container.feature('proc'))
+assistant.use(container.server('express'))
+assistant.use(container.server('websocket'))
+assistant.use(container.feature('docker'))
+assistant.use(container.feature('fs'))
 
-container.features.describe()  // markdown summary of all features
-container.feature('fs').introspect()          // json
-container.feature('fs').introspectAsText()    // markdown
+await assistant.start()
 ```
 
-### Content-aware documentation
+That's an agent harness. Not a chatbot — an operator.
 
-The node container includes `container.docs` powered by [Contentbase](https://github.com/soederpop/contentbase) — query your project's markdown documentation like a database:
+## Build Your Own Binary
 
-```ts
-await container.docs.load()
-const { Tutorial } = container.docs.models
-const tutorials = await container.docs.query(Tutorial).fetchAll()
+Luca isn't just a tool you use — it's a tool that builds tools.
+
+Bootstrap a project, add your own commands, features, endpoints, and assistants, then compile the whole thing into a standalone binary:
+
+```sh
+luca bootstrap my-tool
+cd my-tool
+
+# add your own commands, features, endpoints
+luca scaffold command analyze --description "Run analysis on input data"
+luca scaffold feature myCache --description "Custom caching layer"
+luca scaffold endpoint status --description "Health check endpoint"
+
+# compile to a single binary
+luca bundle
 ```
 
-### Project extensions
+The output is a self-contained executable. No node, no bun, no npm on the target machine. Your users download one file and run it. Your custom commands show up in `my-tool --help`. Your assistant ships inside.
 
-Drop files into convention-based folders and they're auto-discovered:
+## Project Structure
 
-- `commands/` — custom CLI commands, run via `luca <name>`
-- `endpoints/` — file-based HTTP routes, served via `luca serve`
-- `features/` — custom container features
+Convention-based folders are auto-discovered:
+
+```
+commands/       custom CLI commands → luca <name>
+endpoints/      file-based HTTP routes → luca serve
+features/       custom container features → container.feature('<name>')
+assistants/     AI assistants with system prompts and tools
+docs/           content documents queryable via container.docs
+```
 
 Generate boilerplate with `luca scaffold`:
 
@@ -170,33 +189,40 @@ luca scaffold feature myCache --description "Custom caching layer"
 luca scaffold endpoint users --description "User management API"
 ```
 
-### Building an assistant
+## Run Scripts and Markdown
 
-Features can inject their own tools into an assistant via `assistant.use()`. Here's an assistant that can browse the web:
+`luca run` executes TypeScript, JavaScript, and markdown files with the container in scope:
 
-```ts
-import container from '@soederpop/luca'
+````md
+# my-script.md
 
-const browser = container.feature('browserUse', { headed: true })
-const assistant = container.feature('assistant', {
-  systemPrompt: 'You are a web research assistant. Use your browser tools to find information.',
-  model: 'gpt-4.1-mini',
-})
+```ts
+const fs = container.feature('fs')
+const files = await fs.readdir('.')
+console.log(`Found ${files.length} files`)
+```
 
-// browserUse injects its tools — open, click, type, screenshot, extract, etc.
-assistant.use(browser)
-await assistant.start()
+```ts
+const yaml = container.feature('yaml')
+console.log(yaml.stringify({ files }))
+```
+````
 
-await assistant.ask('Go to hacker news and tell me what the top 3 stories are about')
+```sh
+luca run my-script.md
 ```
 
-### AI coding assistant integration
+Blocks share state. Use `--safe` for approval before each block, `--console` to drop into a REPL afterward with accumulated context.
 
-The CLI works great alongside Claude Code, Codex, and other coding assistants:
+## AI Coding Assistant Integration
 
-- `luca describe` gives assistants full API docs for any helper
-- `luca eval` lets them test container expressions before committing code
-- `luca sandbox-mcp` provides a REPL and doc browser as an MCP server
+Luca is designed to work alongside Claude Code, Codex, and other AI coding assistants:
+
+- `luca describe` gives the assistant full API docs for any helper — method signatures, options, events, state shape
+- `luca eval` lets the assistant test container expressions before writing code
+- `luca sandbox-mcp` exposes a REPL and doc browser as an MCP server
+
+The assistant doesn't need to read source files to understand the framework. It asks the framework directly.
 
 ## Development
 
@@ -213,15 +239,10 @@ bun install
 bun run setup
 ```
 
-`bun run setup` applies `git update-index --skip-worktree` to the build artifact stubs so local changes to generated files (from running `build:introspection`, `build:scaffolds`, etc.) are never accidentally committed.
-
 ### Running in dev
 
 ```sh
-# Run the CLI from source (equivalent to the luca binary)
-bun run src/cli/cli.ts
-
-# Examples
+bun run src/cli/cli.ts                           # same as luca binary
 bun run src/cli/cli.ts describe features
 bun run src/cli/cli.ts eval "container.features.available"
 ```
@@ -229,11 +250,8 @@ bun run src/cli/cli.ts eval "container.features.available"
 ### Testing
 
 ```sh
-# Unit tests
-bun test
-
-# Integration tests (may require API keys / env vars)
-bun run test:integration
+bun test                    # unit tests
+bun run test:integration    # integration tests (may require API keys)
 ```
 
 ### Building the binary
@@ -242,13 +260,13 @@ bun run test:integration
 bun run compile
 ```
 
-This runs the full pipeline: introspection generation, scaffold templates, bootstrap code, python bridge, build stamp, then compiles to `dist/luca` via Bun's native compiler.
+Runs the full pipeline: introspection generation, scaffold templates, build stamp, then compiles to `dist/luca` via Bun's native compiler.
 
 ### Project structure
 
 ```
 src/
-  cli/          CLI entry point and commands
+  cli/          CLI entry point and built-in commands
   node/         NodeContainer and server-side features
   web/          WebContainer and browser features
   agi/          AGIContainer — AI assistant layer

package/assistants/codingAssistant/CORE.md

@@ -1,10 +1,15 @@
 ---
+model: qwen/qwen-3.6-27b
+clientOptions:
+  baseURL: http://chief:1234/v1
+  apiKey: sk-local
+contextWindow: 64000
 skills:
   - luca-framework
 ---
 # Coding Assistant
 
-You are a Luca Framework coding assistant. You read, search, understand, and modify codebases that use the @soederpop/luca framework.  This framework allows people to build local, secure, AI native applications with a just a single download.  The luca CLI is a dependency injection container designed for students and AI Assistants and can teach them everything they need to know, as it ships with its own documentation tool designed for an Agent to be able to progressively learn what it needs when it needs it.
+You are a Luca Framework coding assistant. You read, search, understand, and modify codebases that use the luca framework.  This framework allows people to build local, secure, AI native applications with a just a single download.  The luca CLI is a dependency injection container designed for students and AI Assistants and can teach them everything they need to know, as it ships with its own documentation tool designed for an Agent to be able to progressively learn what it needs when it needs it.
 
 ## Luca First
 

package/assistants/codingAssistant/hooks.ts

@@ -1,4 +1,4 @@
-import type { Assistant, AGIContainer } from '@soederpop/luca/agi'
+import type { Assistant, AGIContainer } from 'luca/agi'
 
 declare global {
 	var assistant: Assistant

package/assistants/inkbot/hooks.ts

@@ -1,4 +1,4 @@
-import type { AGIContainer, Assistant } from "@soederpop/luca/agi"
+import type { AGIContainer, Assistant } from "luca/agi"
 
 declare global {
 	var assistant: Assistant

package/assistants/inkbot/tools.ts

@@ -1,4 +1,4 @@
-import container from '@soederpop/luca/agi'
+import container from 'luca/agi'
 import { z } from 'zod'
 
 export const use = [