wip3

README.md

@@ -7,18 +7,40 @@ A Go tool that transpiles TypeScript to JavaScript using esbuild and executes it
 ```
 reichard.io/poiesis/
 ├── cmd/
-│   └── poiesis/          # CLI application entry point
+│   └── poiesis/                    # CLI application entry point
 │       └── main.go
 ├── internal/
-│   ├── builtin/          # Builtin function framework
-│   │   ├── builtin.go
-│   │   └── builtin_test.go
-│   └── runtime/          # TypeScript transpilation and execution
-│       ├── runtime.go
-│       └── runtime_test.go
-└── examples/             # Example TypeScript files
+│   └── runtime/
+│       ├── pkg/
+│       │   └── builtin/            # Builtin framework (framework only)
+│       │       └── builtin.go     # Registration system & type conversion
+│       ├── standard/               # Standard builtin implementations
+│       │   ├── fetch.go           # HTTP fetch builtin
+│       │   └── fetch_test.go      # Tests for fetch
+│       ├── runtime.go              # Transpilation & execution
+│       └── runtime_test.go         # Runtime tests
+└── examples/                       # Example TypeScript files
 ```
 
+## Architecture
+
+The project is cleanly separated into three packages:
+
+1. **`internal/runtime/pkg/builtin`** - The framework for registering builtins and type conversion
+   - Generic registration with automatic type inference
+   - Bidirectional Go ↔ JavaScript type conversion
+   - No builtin implementations (pure framework)
+
+2. **`internal/runtime/standard`** - Standard builtin implementations
+   - `fetch`, `add`, `greet`
+   - Custom type converters for complex types
+   - Independent and easily extensible
+
+3. **`internal/runtime`** - Runtime management
+   - TypeScript transpilation with esbuild
+   - JavaScript execution with goja
+   - Automatically imports and registers standard builtins
+
 ## Installation & Build
 
 ```bash