luca 1.1.2 → 3.0.0

package/.github/workflows/release.yaml

@@ -0,0 +1,169 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Pre-build steps
+        run: |
+          bash scripts/stamp-build.sh
+          bun run build:introspection
+          bun run build:scaffolds
+          bun run build:bootstrap
+          bun run build:python-bridge
+
+      - name: Build Linux binaries
+        run: |
+          mkdir -p dist/release
+          bun build ./src/cli/cli.ts --compile --target=bun-linux-x64 --outfile dist/release/luca-linux-x64 --external node-llama-cpp
+          bun build ./src/cli/cli.ts --compile --target=bun-linux-arm64 --outfile dist/release/luca-linux-arm64 --external node-llama-cpp
+
+      - name: Upload Linux artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: linux-binaries
+          path: dist/release/luca-linux-*
+
+  build-windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Pre-build steps
+        shell: bash
+        run: |
+          bash scripts/stamp-build.sh
+          bun run build:introspection
+          bun run build:scaffolds
+          bun run build:bootstrap
+          bun run build:python-bridge
+
+      - name: Build Windows binary
+        shell: bash
+        run: |
+          mkdir -p dist/release
+          bun build ./src/cli/cli.ts --compile --target=bun-windows-x64 --outfile dist/release/luca-windows-x64.exe --external node-llama-cpp
+
+      - name: Upload Windows artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-binaries
+          path: dist/release/luca-windows-x64.exe
+
+  build-macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Pre-build steps
+        run: |
+          bash scripts/stamp-build.sh
+          bun run build:introspection
+          bun run build:scaffolds
+          bun run build:bootstrap
+          bun run build:python-bridge
+
+      - name: Build macOS binaries
+        run: |
+          mkdir -p dist/release
+          bun build ./src/cli/cli.ts --compile --target=bun-darwin-x64 --outfile dist/release/luca-darwin-x64 --external node-llama-cpp
+          bun build ./src/cli/cli.ts --compile --target=bun-darwin-arm64 --outfile dist/release/luca-darwin-arm64 --external node-llama-cpp
+
+      - name: Import Developer ID Certificate
+        env:
+          CERTIFICATE_P12: ${{ secrets.APPLE_CERTIFICATE_P12 }}
+          CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+        run: |
+          echo "$CERTIFICATE_P12" | base64 --decode > certificate.p12
+          security create-keychain -p "" build.keychain
+          security import certificate.p12 -k build.keychain \
+            -P "$CERTIFICATE_PASSWORD" -T /usr/bin/codesign
+          security list-keychains -s build.keychain
+          security default-keychain -s build.keychain
+          security unlock-keychain -p "" build.keychain
+          security set-key-partition-list -S apple-tool:,apple: \
+            -s -k "" build.keychain
+
+      - name: Sign macOS binaries
+        run: |
+          codesign --sign "Developer ID Application: Demitra Del Fiacco (77WL45HR8M)" \
+            --force --options runtime --timestamp dist/release/luca-darwin-x64
+          codesign --sign "Developer ID Application: Demitra Del Fiacco (77WL45HR8M)" \
+            --force --options runtime --timestamp dist/release/luca-darwin-arm64
+
+      - name: Notarize macOS binaries
+        env:
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          zip dist/release/luca-darwin-x64.zip dist/release/luca-darwin-x64
+          xcrun notarytool submit dist/release/luca-darwin-x64.zip \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --wait
+
+          zip dist/release/luca-darwin-arm64.zip dist/release/luca-darwin-arm64
+          xcrun notarytool submit dist/release/luca-darwin-arm64.zip \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --wait
+
+      - name: Staple notarization
+        run: |
+          xcrun stapler staple dist/release/luca-darwin-x64 || true
+          xcrun stapler staple dist/release/luca-darwin-arm64 || true
+
+      - name: Upload macOS artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-binaries
+          path: dist/release/luca-darwin-*
+          exclude: |
+            dist/release/*.zip
+
+  create-release:
+    needs: [build-linux, build-windows, build-macos]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          merge-multiple: true
+          path: dist/release
+
+      - name: Create draft GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          draft: true
+          generate_release_notes: true
+          files: dist/release/*

package/AGENTS.md

@@ -0,0 +1,99 @@
+# LUCA
+
+Lightweight Universal Conversational Architecture. Runtime is bun.
+
+The runtime is bun, that means no vitest.
+
+Luca provides a system for building runtime `container` objects which provide server and browser applications with all of the dependencies they need to build complete applications.  A `container` is a per process global singleton, event bus, state machine, and dependency injector.  A `container` is either based on a node or browser runtime, and comes with features optimized for that environment.  You can build your own container on top of it, with your own features, clients, servers.  It is very much inspired by docker layer caching.
+
+A `container` could be used for all "business logic" and state, and be a headless provider for an entire application.  The UI, Scripting output, input, etc, are all just functional interfaces and event bindings to the core container and all of its helpers, and their state.
+
+Dependencies consist of Helpers - Features, Clients, Servers, as well as primitives like event buses, observable state.  The `container` contains registries of all available components: `container.features`, `container.clients`, `container.servers`, `container.commands`, `container.endpoints` as well as factory functions to create instances of them: `container.feature('fileManager')`, `container.server('express')`. 
+
+The `container` and its helpers are perfect for scripts and long running services on the backend, or highly reactive and stateful applications on the frontend.  The components can easily talk to eachother, as the `container` on the server provides servers like `container.server('express')` and `container.server('websocket')` as well as `container.client('rest')` and `container.client('websocket')` and others.  
+
+On the frontend the browser container is perfect for highly reactive, stateful web applications, especially works well with React.
+
+## 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"` 
+	- 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
+
+**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
+
+## Coding style and guidelines
+
+- The container is intended to provide a collection of blessed, approved, audited modules that we've built and curated together.  It is intended to be the primary API and interface through the system  
+- The container should provide you with everything you need, and you should not need to be importing dependencies or other modules.  If you find yourself stuck by this constraint, raise this concern, and we can work on finding a way to bring in a feature or client
+- When trying to find paths in the project, use `container.paths.resolve()` or `container.paths.join()` instead of `import { resolve } from 'path'`
+- **NEVER import from `fs`, `path`, or other Node builtins when the container provides equivalents.** Use `container.feature('fs')` for file operations, `container.paths` for path operations. This applies everywhere — command handlers, scripts, and feature implementations alike. If a container feature wraps the functionality, use it.
+
+## Container Utilities
+
+The container provides `container.utils` with common utilities. **Use these instead of importing packages directly** — they work in both node and web environments.
+
+- `container.utils.uuid()` — generates a v4 UUID (use instead of importing `node-uuid` or `crypto`)
+- `container.utils.hashObject(obj)` — deterministic hash of any object
+- `container.utils.stringUtils` — `{ kebabCase, camelCase, upperFirst, lowerFirst, pluralize, singularize }`
+- `container.utils.lodash` — `{ uniq, keyBy, uniqBy, groupBy, debounce, throttle, mapValues, mapKeys, pick, get, set, omit }`
+
+Also available on every container:
+- `container.uuid` — the container's own unique ID
+- `container.paths.resolve()` / `container.paths.join()` — path operations
+
+## Adding a New Feature — Checklist
+
+When creating a new feature (e.g. `gws`), all four of these steps must be completed or `container.feature('gws')` will fail silently or lack type safety:
+
+1. **Feature file** — `src/node/features/gws.ts`
+   - Export the class: `export class Gws extends Feature { ... }`
+   - Register at bottom: `export default features.register('gws', Gws)`
+
+2. **Side-effect import** — `src/node/container.ts` (import block ~line 20-63)
+   - Add `import "./features/gws";` (this triggers registration)
+
+3. **Type import + re-export** — `src/node/container.ts` (type imports ~line 65-148)
+   - Add `import type { Gws } from './features/gws';`
+   - Add `type Gws,` to the `export { ... }` block
+
+4. **Feature type mapping** — `src/node/container.ts` (`NodeFeatures` interface ~line 170-215)
+   - Add `gws: typeof Gws;` to the `NodeFeatures` interface
+
+Missing step 2 = feature never registers (invisible).
+Missing steps 3-4 = no autocomplete, `container.feature('gws')` returns `Feature` not `Gws`.
+
+If the feature has a test, it goes in `test/gws.test.ts`.
+
+## Type Safety and Introspection
+
+- Zod does a lot of the heavy lifting for us with its type inference
+- For more descriptive things like class descriptions, method descriptions, we rely on jsdoc blocks.  These are parsed and used to generate modules we commit to source.  We shouldn't let these drift, so for this reason we have a pre-commit hook which ensures they're up to date
+- We rely on module augmentation a lot to make sure `container.feature()` can provide type signatures for everything that gets added to it by extension modules down the road.  ( kind of like we did with AGIContainer extending NodeContainer )
+
+## Testing
+
+- Test runner is **bun** (not vitest). Do not import from or add vitest.
+- `bun test` or `bun run test` — runs unit tests only (`test/*.test.ts`)
+- `bun run test:integration` — runs integration tests in `test-integration/` that hit real APIs/CLIs (gated by env vars)
+- Import `mock`, `spyOn` from `bun:test` when needed. If you import anything from `bun:test`, you must also import `describe`, `it`, `expect`, etc. from there (importing disables auto-globals).
+- **ALL tests must pass. Zero tolerance for test failures.** The ESBuild feature's "service is no longer running" error is a known critical bug — if you encounter it, fix it. Do not ignore it, do not skip it, do not leave it broken. This applies to every test: if a test fails, that is a blocker. Fix the root cause.
+
+## API Docs
+
+- See [docs/apis](./docs/apis/) for detailed API descriptions of the public methods and options for creating various helpers
+- See [docs/examples](./docs/examples/) for examples of using each feature.  NOTE: These docs are runnable so you can see the output of the code blocks.  `luca run docs/examples/grep` for example
+- See [docs/tutorials](./docs/tutorials/) for longer form tutorials on various subjects and best practices
+
+## Git Strategy
+
+- We generally roll all on main.  Commit your changes after you're done, only your changes.  Leave a good message, tell me why don't just tell me what.  Don't gimme that coauthored by whoever bullshit.  The streets know we're one.

package/CLAUDE.md

@@ -0,0 +1,115 @@
+# LUCA
+
+Lightweight Universal Conversational Architecture. Runtime is bun.
+
+The runtime is bun, that means no vitest.
+
+Luca provides a system for building runtime `container` objects which provide server and browser applications with all of the dependencies they need to build complete applications.  A `container` is a per process global singleton, event bus, state machine, and dependency injector.  A `container` is either based on a node or browser runtime, and comes with features optimized for that environment.  You can build your own container on top of it, with your own features, clients, servers.  It is very much inspired by docker layer caching.
+
+A `container` could be used for all "business logic" and state, and be a headless provider for an entire application.  The UI, Scripting output, input, etc, are all just functional interfaces and event bindings to the core container and all of its helpers, and their state.
+
+Dependencies consist of Helpers - Features, Clients, Servers, as well as primitives like event buses, observable state.  The `container` contains registries of all available components: `container.features`, `container.clients`, `container.servers`, `container.commands`, `container.endpoints` as well as factory functions to create instances of them: `container.feature('fileManager')`, `container.server('express')`. 
+
+The `container` and its helpers are perfect for scripts and long running services on the backend, or highly reactive and stateful applications on the frontend.  The components can easily talk to eachother, as the `container` on the server provides servers like `container.server('express')` and `container.server('websocket')` as well as `container.client('rest')` and `container.client('websocket')` and others.  
+
+On the frontend the browser container is perfect for highly reactive, stateful web applications, especially works well with React.
+
+## 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"` 
+	- 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
+
+**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
+
+## OpenAI Tool Schemas (Zod → JSON Schema)
+
+**OpenAI requires `required` to list ALL property keys in `properties`**, even optional ones. Zod's `toJSONSchema()` only puts non-optional fields in `required`, which OpenAI rejects with "Missing 'X'" errors. The `assistant.addTool()` method handles this automatically by always setting `required: Object.keys(properties)`. Do NOT use `z.any()` or `z.record(z.any())` in tool schemas — Zod v4's `toJSONSchema()` cannot serialize `z.any()` and will throw `schema._zod is undefined`. Use concrete types like `z.string()` instead (e.g. accept a JSON string and parse it at runtime).
+
+## Coding style and guidelines
+
+- The container is intended to provide a collection of blessed, approved, audited modules that we've built and curated together.  It is intended to be the primary API and interface through the system  
+- The container should provide you with everything you need, and you should not need to be importing dependencies or other modules.  If you find yourself stuck by this constraint, raise this concern, and we can work on finding a way to bring in a feature or client
+- When trying to find paths in the project, use `container.paths.resolve()` or `container.paths.join()` instead of `import { resolve } from 'path'`
+- **`paths.join()` vs `paths.resolve()` gotcha:** `paths.join()` always prepends `container.cwd` — even if you pass an absolute path as the first arg. Use `paths.resolve(absolutePath, 'sub')` when the base is already absolute (e.g. `os.tmpdir`). `resolve` respects absolute first args just like Node's `path.resolve`.
+- **NEVER import from `fs`, `path`, or other Node builtins when the container provides equivalents.** Use `container.feature('fs')` for file operations, `container.paths` for path operations. This applies everywhere — command handlers, scripts, and feature implementations alike. If a container feature wraps the functionality, use it.
+
+## Container Utilities
+
+The container provides `container.utils` with common utilities. **Use these instead of importing packages directly** — they work in both node and web environments.
+
+- `container.utils.uuid()` — generates a v4 UUID (use instead of importing `node-uuid` or `crypto`)
+- `container.utils.hashObject(obj)` — deterministic hash of any object
+- `container.utils.stringUtils` — `{ kebabCase, camelCase, upperFirst, lowerFirst, pluralize, singularize }`
+- `container.utils.lodash` — `{ uniq, keyBy, uniqBy, groupBy, debounce, throttle, mapValues, mapKeys, pick, get, set, omit }`
+
+Also available on every container:
+- `container.uuid` — the container's own unique ID
+- `container.paths.resolve()` / `container.paths.join()` — path operations
+
+## Adding a New Feature — Checklist
+
+When creating a new feature (e.g. `gws`), all four of these steps must be completed or `container.feature('gws')` will fail silently or lack type safety:
+
+1. **Feature file** — `src/node/features/gws.ts`
+   - Export the class: `export class Gws extends Feature { ... }`
+   - Register inside the class: `static { Feature.register(this, 'gws') }`
+   - Default export is just the class: `export default Gws`
+
+2. **Side-effect import** — `src/node/container.ts` (import block ~line 20-63)
+   - Add `import "./features/gws";` (this triggers registration)
+
+3. **Type import + re-export** — `src/node/container.ts` (type imports ~line 65-148)
+   - Add `import type { Gws } from './features/gws';`
+   - Add `type Gws,` to the `export { ... }` block
+
+4. **Feature type mapping** — `src/node/container.ts` (`NodeFeatures` interface ~line 170-215)
+   - Add `gws: typeof Gws;` to the `NodeFeatures` interface
+
+Missing step 2 = feature never registers (invisible).
+Missing steps 3-4 = no autocomplete, `container.feature('gws')` returns `Feature` not `Gws`.
+
+If the feature has a test, it goes in `test/gws.test.ts`.
+
+## Type Safety and Introspection
+
+- Zod does a lot of the heavy lifting for us with its type inference
+- For more descriptive things like class descriptions, method descriptions, we rely on jsdoc blocks.  These are parsed and used to generate modules we commit to source.  We shouldn't let these drift, so for this reason we have a pre-commit hook which ensures they're up to date
+- We rely on module augmentation a lot to make sure `container.feature()` can provide type signatures for everything that gets added to it by extension modules down the road.  ( kind of like we did with AGIContainer extending NodeContainer )
+
+## Generated Files — Build Artifacts
+
+**Files matching `generated.ts` or `.generated*.ts` are BUILD ARTIFACTS, not source of truth.** They are produced by the introspection system (which parses JSDoc blocks, Zod schemas, etc.) and bundled into the binary at compile time. **Never edit these files directly** — your changes will be overwritten on the next build.
+
+The source of truth for scaffolds and templates is the markdown files and the actual source code with their JSDoc annotations. If scaffold output is wrong, fix the markdown source or the JSDoc blocks on the real classes, then rebuild.
+
+This means **JSDoc blocks on helpers (features, clients, servers) must be valid and complete** — they are picked up by the introspection system, used to generate API docs, scaffold tutorials, and the `luca describe` output. Treat JSDoc as documentation infrastructure, not comments.
+
+## Testing
+
+- Test runner is **bun** (not vitest). Do not import from or add vitest.
+- `bun test` or `bun run test` — runs unit tests only (`test/*.test.ts`)
+- `bun run test:integration` — runs integration tests in `test-integration/` that hit real APIs/CLIs (gated by env vars)
+- Import `mock`, `spyOn` from `bun:test` when needed. If you import anything from `bun:test`, you must also import `describe`, `it`, `expect`, etc. from there (importing disables auto-globals).
+- **ALL tests must pass. Zero tolerance for test failures.** The ESBuild feature's "service is no longer running" error is a known critical bug — if you encounter it, fix it. Do not ignore it, do not skip it, do not leave it broken. This applies to every test: if a test fails, that is a blocker. Fix the root cause.
+
+## API Docs
+
+- See [docs/apis](./docs/apis/) for detailed API descriptions of the public methods and options for creating various helpers
+- See [docs/examples](./docs/examples/) for examples of using each feature.  NOTE: These docs are runnable so you can see the output of the code blocks.  `luca run docs/examples/grep` for example
+- See [docs/tutorials](./docs/tutorials/) for longer form tutorials on various subjects and best practices
+
+## Git Strategy
+
+- We generally roll all on main.  Commit your changes after you're done, only your changes.  Leave a good message, tell me why don't just tell me what.  Don't gimme that coauthored by whoever bullshit.  The streets know we're one.
+
+- Always commit your work

package/CNAME

@@ -0,0 +1 @@
+luca-js.soederpop.com

package/README.md

@@ -1,18 +1,267 @@
-# Luca · [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/iZemil/luca/blob/main/LICENSE) ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/izemil/luca)
+# Luca
 
-Tiny [NPM package](https://www.npmjs.com/package/luca) to check urls by name list and getting statuses.
+**Lightweight Universal Conversational Architecture**
 
-<img src="./logo.png" alt="luca" width="256"/>
+A single binary CLI that ships 40+ self-documenting features, clients, and servers. No `npm install`, no setup — download it and start building.
+
+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.
+
+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.
 
 ## Installation
 
--   For cli usage install the package globally `npm i luca -g`
+### Quick install (macOS/Linux)
+
+```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.
+
+### Manual download
+
+Grab the latest release for your platform from [GitHub Releases](https://github.com/soederpop/luca/releases/latest):
+
+| Platform | Binary |
+|----------|--------|
+| macOS (Apple Silicon) | `luca-darwin-arm64` |
+| macOS (Intel) | `luca-darwin-x64` |
+| Linux x64 | `luca-linux-x64` |
+| 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.
+
+### Explore
+
+```sh
+luca                              # list all commands
+luca describe features            # index of 40+ features
+luca describe fs                  # full docs for any feature
+luca describe fs.readFile         # drill into a specific method
+luca eval "container.features.available"  # run code with the container in scope
+luca console                      # full REPL
+```
+
+### Run scripts and markdown
+
+`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:
+
+````md
+# my-script.md
+
+Grab some data and print it:
+
+```ts
+const fs = container.feature('fs')
+const files = await fs.readdir('.')
+console.log(`Found ${files.length} files`)
+```
+
+Then do something with it:
+
+```ts
+const yaml = container.feature('yaml')
+console.log(yaml.stringify({ files }))
+```
+````
+
+```sh
+luca run my-script.md
+```
+
+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.
+
+### Serve
+
+```sh
+luca serve   # serves endpoints/ folder as HTTP routes
+```
+
+See [`docs/CLI.md`](./docs/CLI.md) for the full CLI reference.
+
+## Importing the container into your own scripts / modules
+
+```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.
+
+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
+
+**Static import:**
+
+```js
+import container from 'https://esm.sh/@soederpop/luca/web'
+
+container.features.available  // ['fetch', 'state', 'ui', ...]
+```
+
+**Dynamic import:**
+
+```js
+const { default: container } = await import('https://esm.sh/@soederpop/luca/web')
+
+container.features.available  // same singleton
+```
+
+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.
 
-## CLI Usage
+## How It Works
 
--   Get docs `luca -h`
+### Self-documenting at runtime
+
+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.
+
+```ts
+import container from '@soederpop/luca'
+
+container.features.available   // ['fs','git','proc','vault',...]
+container.clients.available    // ['rest','websocket']
+container.servers.available    // ['express','websocket','ipc','mcp']
+
+container.features.describe()  // markdown summary of all features
+container.feature('fs').introspect()          // json
+container.feature('fs').introspectAsText()    // markdown
+```
+
+### Content-aware documentation
+
+The node container includes `container.docs` powered by [Contentbase](https://github.com/soederpop/contentbase) — query your project's markdown documentation like a database:
+
+```ts
+await container.docs.load()
+const { Tutorial } = container.docs.models
+const tutorials = await container.docs.query(Tutorial).fetchAll()
+```
+
+### Project extensions
+
+Drop files into convention-based folders and they're auto-discovered:
+
+- `commands/` — custom CLI commands, run via `luca <name>`
+- `endpoints/` — file-based HTTP routes, served via `luca serve`
+- `features/` — custom container features
+
+Generate boilerplate with `luca scaffold`:
+
+```sh
+luca scaffold command myTask --description "Automate something"
+luca scaffold feature myCache --description "Custom caching layer"
+luca scaffold endpoint users --description "User management API"
+```
+
+### Building an assistant
+
+Features can inject their own tools into an assistant via `assistant.use()`. Here's an assistant that can browse the web:
+
+```ts
+import container from '@soederpop/luca'
+
+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',
+})
+
+// browserUse injects its tools — open, click, type, screenshot, extract, etc.
+assistant.use(browser)
+await assistant.start()
+
+await assistant.ask('Go to hacker news and tell me what the top 3 stories are about')
+```
+
+### AI coding assistant integration
+
+The CLI works great alongside Claude Code, Codex, and other coding assistants:
+
+- `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
 
 ## Development
 
--   main lib dev `yarn dev` and work with dev.ts file
--   cli dev `yarn dev:cli <comand> [options]`
+### Prerequisites
+
+- [Bun](https://bun.sh) (runtime and test runner)
+
+### Setup
+
+```sh
+git clone https://github.com/soederpop/luca.git
+cd luca
+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 describe features
+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
+```
+
+### Building the binary
+
+```sh
+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.
+
+### Project structure
+
+```
+src/
+  cli/          CLI entry point and commands
+  node/         NodeContainer and server-side features
+  web/          WebContainer and browser features
+  agi/          AGIContainer — AI assistant layer
+  schemas/      Shared Zod schemas
+  react/        React bindings
+test/           Unit tests
+test-integration/  Integration tests
+docs/
+  apis/         Generated API docs
+  examples/     Runnable examples (luca run docs/examples/grep)
+  tutorials/    Longer-form guides
+```
+
+## License
+
+MIT