zuzu 0.2.1-java → 0.2.3-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30a4b0d6a387e3fcd5f11779007cca23c75cfc8022e0efaf7b59a51a774f8e9c
-  data.tar.gz: 85912884d1c9a34aea94735f909f9702ecb5e732b09f695e842c5edebab5ccd2
+  metadata.gz: fd72fe083faded7ee6c7c7461125625f70a02a062da88eb9b28ed459cf767e40
+  data.tar.gz: 2096e3e9972ac19255f8b3f2ecdff467a979ac6cd9efe378f1bc226f625ce6aa
 SHA512:
-  metadata.gz: 7df32882674e79a21e55e8f81857eb264c88f168090619ce9af3bda6c356858fd6fda0db17618e808c8b67fd6f3c81e31e14c26857837a96858284b29533ce0b
-  data.tar.gz: 571984d3abb3f76e8afa169fb88257c18441cac52f5e2a085067b2a189af0772e354e0b0c999a73be09cb13365eb3d6c52a98b772717803b5a27fc553fcf099c
+  metadata.gz: 779b1e6821bcbe4199fa08868a8e0f4be6d197fae68e42ed6f46605f02c8e402a1e05e34c79b2abae71d7e4c06b4eaacd2a1b20c206eecf3ef64fc134d6762f4
+  data.tar.gz: 3453ba743830abb356d912a7f770fd27a7b22869a376830697b9419df11eea2c2cd9ce41fc01cbc827a5ea3370e913f05f8341a5c74a560111d30c40c899dedc

data/README.md

@@ -1,9 +1,22 @@
 # Zuzu
 
-**Local-first agentic desktop apps with JRuby.**
+**Build AI-native desktop apps that run entirely on the user's machine.**
 
-Zuzu is a framework for building privacy-respecting AI desktop assistants that
-run entirely on your machine. No cloud APIs required — your data stays local.
+Every application you install on an operating system does the same fundamental thing: it translates human intent into OS system calls. A text editor writes bytes to disk. A browser opens network connections. At its core, every installed app is an orchestrator of operating system capabilities.
+
+LLMs are simply a more expressive interface for exactly that orchestration. Zuzu is a framework built on this premise — for developers who want to ship installable, AI-native desktop apps where the intelligence runs on the user's hardware, not in a data center.
+
+**Why does this matter?**
+
+- **Privacy by architecture.** The agent operates inside AgentFS — a sandboxed virtual filesystem backed by a single SQLite file. It cannot touch the host OS unless you explicitly open that door. There is no network call to make, no token to rotate, no terms of service that changes next quarter.
+
+- **Deployable like software, not like a service.** Package your app as a single `.jar` — or go further with `zuzu package` and produce a native installer (`.dmg`/`.app` on macOS, `.deb` on Linux, `.exe` on Windows) that bundles a minimal JRE via jlink. Users download, double-click, and run. No Java pre-installed. No Docker. No cloud subscription. No infrastructure to maintain.
+
+- **Built for regulated environments.** A therapist keeping session notes, an auditor running confidential analysis, a corporate team in a restricted environment — these are exactly the users who benefit most from powerful AI but are currently blocked by cloud dependency. A bundled LLM in a self-contained Java application needs no external approval to run.
+
+- **Developer experience that matches how software is actually built today.** `zuzu new my_app` scaffolds a project pre-wired for Claude Code: CLAUDE.md, skills for `/setup`, `/add-tool`, `/customize`, and `/debug` — all enforcing Zuzu's patterns. Open the folder, start your coding agent, describe what you want to build.
+
+→ [Why Zuzu exists](docs/why.md) · [Quick Demo](https://raw.githubusercontent.com/parolkar/zuzu/refs/heads/main/docs/demo/zuzu_quick_demo_01.mp4)
 
 <video src="https://raw.githubusercontent.com/parolkar/zuzu/refs/heads/main/docs/demo/zuzu_quick_demo_01.mp4" controls width="100%"></video>
 [Quick Demo](https://raw.githubusercontent.com/parolkar/zuzu/refs/heads/main/docs/demo/zuzu_quick_demo_01.mp4)
@@ -32,7 +45,7 @@ cd zuzu
 bin/setup
 ```
 
-`bin/setup` installs Java 21, JRuby 10.0.4.0, and all gem dependencies
+`bin/setup` installs Java 21, JRuby 10.0.3.0, and all gem dependencies
 automatically. If you prefer manual setup, see [Manual Setup](#manual-setup)
 below.
 
@@ -61,9 +74,11 @@ Edit `app.rb` to point at your model:
 
 ```ruby
 Zuzu.configure do |c|
-  c.app_name       = 'My Assistant'
-  c.llamafile_path = File.expand_path('models/llava-v1.5-7b-q4.llamafile', __dir__)
-  c.db_path        = File.expand_path('.zuzu/zuzu.db', __dir__)
+  c.app_name = 'My Assistant'
+  # Works both when run directly and from a packaged .jar
+  base = __dir__.to_s.start_with?('uri:classloader:') ? Dir.pwd : __dir__
+  c.llamafile_path = File.join(base, 'models', 'llava-v1.5-7b-q4.llamafile')
+  c.db_path        = File.join(base, '.zuzu', 'zuzu.db')
   c.port           = 8080
 end
 ```
@@ -71,16 +86,11 @@ end
 Launch:
 
 ```bash
-# macOS (SWT requires first-thread access):
-JRUBY_OPTS="-J-XstartOnFirstThread -J--enable-native-access=ALL-UNNAMED" bundle exec ruby app.rb
-
-# Linux:
-JRUBY_OPTS="-J--enable-native-access=ALL-UNNAMED" bundle exec ruby app.rb
+bundle exec zuzu start
 ```
 
-You'll see a native desktop window with a file browser on the left and a chat
-interface on the right. The llamafile model starts automatically in the
-background.
+You'll see a native desktop chat window. The llamafile model starts automatically
+in the background. Click **Admin Panel** to browse the AgentFS virtual filesystem.
 
 ---
 
@@ -90,18 +100,14 @@ If `bin/setup` doesn't suit your workflow, follow these steps.
 
 ### 1. Install Java 21+
 
-**macOS (Homebrew):**
+**macOS (Homebrew — recommended):**
 
 ```bash
-brew install openjdk@21
+brew install --cask temurin@21
 ```
 
-Add to your shell profile (`~/.zshrc` or `~/.bash_profile`):
-
-```bash
-export JAVA_HOME=$(/usr/libexec/java_home -v 21)
-export PATH="$JAVA_HOME/bin:$PATH"
-```
+Temurin is the Eclipse/Adoptium OpenJDK distribution. The cask sets up
+`JAVA_HOME` automatically — no manual PATH changes needed.
 
 **macOS (SDKMAN):**
 
@@ -125,17 +131,17 @@ java -version
 # → openjdk version "21.x.x" ...
 ```
 
-### 2. Install JRuby 10.0.4.0 via rbenv
+### 2. Install JRuby 10.0.3.0 via rbenv
 
 ```bash
 # Install rbenv if needed
 brew install rbenv ruby-build   # macOS
 # or: https://github.com/rbenv/rbenv#installation
 
-rbenv install jruby-10.0.4.0
-rbenv local jruby-10.0.4.0
+rbenv install jruby-10.0.3.0
+rbenv local jruby-10.0.3.0
 ruby -v
-# → jruby 10.0.4.0 (ruby 3.x.x) ...
+# → jruby 10.0.3.0 (ruby 3.x.x) ...
 ```
 
 ### 3. Install Gems
@@ -289,13 +295,47 @@ fs.kv_get('last_query')            # → "weather in Tokyo"
 
 ### Packaging as .jar
 
-Use Warbler to create a standalone Java archive:
+Package your app as a standalone Java archive with a single command:
+
+```bash
+bundle exec zuzu package
+```
+
+This auto-installs Warbler if needed, generates the necessary launcher, and
+produces a `.jar` named after your app directory. Run it with:
 
 ```bash
-gem install warbler
-warble jar
-java -XstartOnFirstThread -jar zuzu-app.jar   # macOS
-java -jar zuzu-app.jar                        # Linux
+java -XstartOnFirstThread -jar my_app.jar   # macOS
+java -jar my_app.jar                        # Linux / Windows
+```
+
+> **Note:** Place your llamafile model in a `models/` directory alongside the
+> `.jar` — models are not bundled into the archive.
+
+### Packaging as a native installer (no Java required for users)
+
+After building the JAR, `zuzu package` asks if you want to go further:
+
+```
+Bundle into a self-contained native executable? (no Java required for users) [y/N]:
+```
+
+Type `y` and Zuzu uses **jpackage** (bundled with JDK 21+) to produce a native
+installer that includes a minimal JRE — users never need to install Java:
+
+| Platform | Output |
+|----------|--------|
+| macOS | `.dmg` with a drag-to-Applications `.app` |
+| Linux | `.deb` package |
+| Windows | `.exe` installer |
+
+The model file is not bundled (it can be gigabytes). After installing, users
+place it in the platform user-data directory that Zuzu prints at build time:
+
+```
+macOS:   ~/Library/Application Support/<AppName>/models/<model>.llamafile
+Linux:   ~/.local/share/<AppName>/models/<model>.llamafile
+Windows: %APPDATA%\<AppName>\models\<model>.llamafile
 ```
 
 ---
@@ -323,6 +363,7 @@ end
 ```
 zuzu new APP_NAME    Scaffold a new Zuzu application
 zuzu start           Launch the Zuzu app in the current directory
+zuzu package         Package the app as a standalone .jar
 zuzu console         Open an IRB session with Zuzu loaded
 zuzu version         Print the Zuzu version
 zuzu help            Show this message

data/bin/setup

@@ -20,12 +20,9 @@ if java -version 2>&1 | grep -q 'version "2[1-9]\|version "3'; then
 else
   warn "Java 21+ not found."
   if [[ "$OSTYPE" == darwin* ]]; then
-    step "Installing Java 21 via Homebrew"
-    brew install openjdk@21
-    echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 21)' >> ~/.zshrc
-    export JAVA_HOME=$(/usr/libexec/java_home -v 21)
-    export PATH="$JAVA_HOME/bin:$PATH"
-    echo "  Installed. Restart your shell or run: source ~/.zshrc"
+    step "Installing Java 21 via Homebrew (Temurin)"
+    brew install --cask temurin@21
+    echo "  Installed. Restart your shell to pick up JAVA_HOME."
   elif [[ "$OSTYPE" == linux-gnu* ]]; then
     step "Installing Java 21 via apt"
     sudo apt-get update -qq && sudo apt-get install -y openjdk-21-jdk

data/bin/zuzu

@@ -33,10 +33,13 @@ when 'new'
   app_dir = File.expand_path(app_name)
   abort "Directory '#{app_name}' already exists." if File.exist?(app_dir)
 
-  template_src = File.expand_path('../templates/app.rb', __dir__)
+  templates_dir = File.expand_path('../templates', __dir__)
 
   FileUtils.mkdir_p(app_dir)
-  FileUtils.cp(template_src, File.join(app_dir, 'app.rb'))
+  FileUtils.cp(File.join(templates_dir, 'app.rb'),    File.join(app_dir, 'app.rb'))
+  FileUtils.cp(File.join(templates_dir, 'AGENTS.md'), File.join(app_dir, 'AGENTS.md'))
+  FileUtils.cp(File.join(templates_dir, 'CLAUDE.md'), File.join(app_dir, 'CLAUDE.md'))
+  FileUtils.cp_r(File.join(templates_dir, '.claude'), File.join(app_dir, '.claude'))
 
   # Generate Gemfile — uses local path when running from source tree,
   # published gem when installed via `gem install zuzu`.
@@ -55,6 +58,9 @@ when 'new'
   puts "Created new Zuzu app: #{app_name}/"
   puts "  #{app_name}/app.rb"
   puts "  #{app_name}/Gemfile"
+  puts "  #{app_name}/AGENTS.md"
+  puts "  #{app_name}/CLAUDE.md"
+  puts "  #{app_name}/.claude/skills/ (setup, add-tool, customize, debug)"
   puts ''
   if DEV_MODE
     puts "  (dev mode: Gemfile points to #{ZUZU_ROOT})"
@@ -69,6 +75,15 @@ when 'new'
 when 'start'
   entry = ['app.rb', 'lib/app.rb'].find { |f| File.exist?(f) }
   abort 'No app.rb found. Run `zuzu start` from your app directory.' unless entry
+
+  # SWT on Java 21+ requires --enable-native-access=ALL-UNNAMED.
+  # JVM flags must be set before the JVM starts, so re-exec via bundle
+  # with the flag injected into JRUBY_OPTS if it isn't already present.
+  unless ENV['JRUBY_OPTS'].to_s.include?('enable-native-access')
+    ENV['JRUBY_OPTS'] = "#{ENV['JRUBY_OPTS']} -J--enable-native-access=ALL-UNNAMED".strip
+    exec('bundle', 'exec', 'zuzu', 'start')
+  end
+
   load File.expand_path(entry)
 
 when 'package'
@@ -110,16 +125,106 @@ when 'package'
   puts 'Packaging app as zuzu-app.jar ...'
   puts '  (this may take a minute)'
   success = Bundler.with_unbundled_env { system(warble_bin, 'jar') }
-  if success
-    puts ''
-    jar = Dir['*.jar'].first || 'app.jar'
-    puts "Done! Created: #{jar}"
-    puts ''
-    puts 'Run it with:'
-    puts "  java -XstartOnFirstThread -jar #{jar}   # macOS"
-    puts "  java -jar #{jar}                        # Linux / Windows"
+  abort 'warble jar failed. Check output above for details.' unless success
+
+  jar = Dir['*.jar'].first || 'app.jar'
+  puts ''
+  puts "Done! Created: #{jar}"
+  puts ''
+  puts 'Run it with:'
+  puts "  java -XstartOnFirstThread -jar #{jar}   # macOS"
+  puts "  java -jar #{jar}                        # Linux / Windows"
+  puts ''
+
+  # ── jpackage: optional self-contained native executable ─────────────────
+  # jpackage (JDK 14+) bundles a minimal JRE via jlink so users don't need
+  # Java pre-installed. Model files can't be bundled — they're resolved from
+  # the platform user-data directory at runtime via the zuzu.model JVM property.
+
+  jpackage_bin = `which jpackage 2>/dev/null`.strip
+  if jpackage_bin.empty?
+    puts 'Tip: Install JDK 21+ to create a self-contained executable (no Java required for users).'
   else
-    abort 'warble jar failed. Check output above for details.'
+    print 'Bundle into a self-contained native executable? (no Java required for users) [y/N]: '
+    $stdout.flush
+    answer = $stdin.gets.to_s.strip.downcase
+
+    if answer == 'y' || answer == 'yes'
+      # ── detect / ask for model filename ───────────────────────────────────
+      model_files = Dir['models/*.llamafile']
+      model_name = if model_files.length == 1
+                     puts "Using model: #{File.basename(model_files.first)}"
+                     File.basename(model_files.first)
+                   elsif model_files.length > 1
+                     puts 'Model files found in models/:'
+                     model_files.each { |f| puts "  #{File.basename(f)}" }
+                     print 'Enter model filename: '
+                     $stdout.flush
+                     $stdin.gets.to_s.strip
+                   else
+                     print 'Enter model filename (e.g. llava-v1.5-7b-q4.llamafile): '
+                     $stdout.flush
+                     $stdin.gets.to_s.strip
+                   end
+      abort 'No model filename provided.' if model_name.to_s.empty?
+
+      print 'App version [1.0.0]: '
+      $stdout.flush
+      version_input = $stdin.gets.to_s.strip
+      app_version = version_input.empty? ? '1.0.0' : version_input
+
+      app_name = File.basename(Dir.pwd).gsub(/[^a-zA-Z0-9._-]/, '-')
+
+      platform = RbConfig::CONFIG['host_os']
+      pkg_type  = case platform
+                  when /darwin/ then 'dmg'
+                  when /linux/  then 'deb'
+                  else               'exe'
+                  end
+
+      FileUtils.mkdir_p('dist')
+
+      java_opts = [
+        '--enable-native-access=ALL-UNNAMED',
+        "-Dzuzu.model=#{model_name}"
+      ]
+      java_opts << '-XstartOnFirstThread' if platform =~ /darwin/
+
+      jpackage_args = [
+        jpackage_bin,
+        '--type',        pkg_type,
+        '--name',        app_name,
+        '--app-version', app_version,
+        '--input',       '.',
+        '--main-jar',    jar,
+        '--main-class',  'org.jruby.JarBootstrapMain',
+        '--dest',        'dist'
+      ]
+      java_opts.each { |opt| jpackage_args.push('--java-options', opt) }
+
+      puts ''
+      puts "Building native #{pkg_type.upcase} installer with jpackage..."
+      puts '  (this may take a minute)'
+      native_ok = system(*jpackage_args)
+
+      if native_ok
+        puts ''
+        puts 'Done! Native installer created in dist/'
+        pkg_file = Dir["dist/*.#{pkg_type}"].first
+        puts "  #{pkg_file}" if pkg_file
+        puts ''
+        puts 'Important — place your model file at:'
+        model_dest = case platform
+                     when /darwin/ then "  ~/Library/Application\\ Support/#{app_name}/models/#{model_name}"
+                     when /linux/  then "  ~/.local/share/#{app_name}/models/#{model_name}"
+                     else               "  %APPDATA%\\#{app_name}\\models\\#{model_name}"
+                     end
+        puts model_dest
+        puts '  (create the directory if it does not exist)'
+      else
+        warn 'jpackage failed. Check output above for details.'
+      end
+    end
   end
 
 when 'console'

data/lib/zuzu/agent.rb

@@ -11,22 +11,13 @@ module Zuzu
     TOOL_CALL_RE   = /<zuzu_tool_call>(.*?)<\/zuzu_tool_call>/m
     TOOL_RESULT_RE = /<zuzu_tool_result>.*?<\/zuzu_tool_result>/m
 
-    SYSTEM_PROMPT = <<~PROMPT.strip
+    BASE_PROMPT = <<~PROMPT
       You are Zuzu, a helpful desktop AI assistant.
 
       You have access to a sandboxed virtual filesystem called AgentFS. It is completely
       separate from the host computer's filesystem. All file paths refer to AgentFS only.
       You cannot access or modify any files on the host system.
 
-      Available tools — use the tag format shown below:
-
-      - write_file     : Write text to an AgentFS file. Args: path (string), content (string)
-      - read_file      : Read an AgentFS file. Args: path (string)
-      - list_directory : List an AgentFS directory. Args: path (string, default "/")
-      - run_command    : Run a sandboxed command against AgentFS. Args: command (string)
-                         Supported: ls [path], cat <path>, pwd, echo <text>
-      - http_get       : Fetch a public URL from the internet. Args: url (string)
-
       To call a tool, output exactly this on its own line:
       <zuzu_tool_call>{"name":"TOOL_NAME","args":{"key":"value"}}</zuzu_tool_call>
 
@@ -51,7 +42,7 @@ module Zuzu
       # Only system prompt + current message — no history injected into agent context.
       # Prior non-tool-call responses cause models to skip tool use.
       messages = [
-        { 'role' => 'system', 'content' => SYSTEM_PROMPT },
+        { 'role' => 'system', 'content' => build_system_prompt },
         { 'role' => 'user',   'content' => user_message }
       ]
 
@@ -100,6 +91,22 @@ module Zuzu
 
     private
 
+    def build_system_prompt
+      tool_lines = ToolRegistry.tools.map do |t|
+        args = t.schema[:properties]&.keys&.map(&:to_s)&.join(', ')
+        line = "- #{t.name} : #{t.description}"
+        line += " Args: #{args}" if args && !args.empty?
+        line
+      end.join("\n")
+
+      extras = Zuzu.config.system_prompt_extras.to_s.strip
+
+      prompt = BASE_PROMPT.dup
+      prompt << "\nAvailable tools:\n#{tool_lines}\n"
+      prompt << "\n#{extras}" unless extras.empty?
+      prompt.strip
+    end
+
     def extract_tool_calls(content)
       content.scan(TOOL_CALL_RE).filter_map do |match|
         data = JSON.parse(match[0].strip)

data/lib/zuzu/config.rb

@@ -11,17 +11,18 @@ module Zuzu
   #
   class Config
     attr_accessor :port, :model, :channels, :log_level, :app_name,
-                  :window_width, :window_height
+                  :window_width, :window_height, :system_prompt_extras
 
-    attr_reader :db_path, :llamafile_path
+    attr_reader :db_path
 
     def initialize
       @port           = 8080
       @model          = 'LLaMA_CPP'
       @db_path        = File.join('.zuzu', 'zuzu.db')
       @llamafile_path = nil
-      @channels       = []
-      @log_level      = :info
+      @channels             = []
+      @log_level            = :info
+      @system_prompt_extras = nil
       @app_name       = 'Zuzu'
       @window_width   = 860
       @window_height  = 620
@@ -36,6 +37,28 @@ module Zuzu
     def llamafile_path=(path)
       @llamafile_path = path ? File.expand_path(path) : path
     end
+
+    # When running as a jpackage native executable, the model is NOT bundled
+    # in the app. Instead it lives in the platform user-data directory and its
+    # filename is injected via the `-Dzuzu.model=<filename>` JVM property set
+    # by jpackage at build time.
+    def llamafile_path
+      if defined?(Java) &&
+         (model_name = Java::JavaLang::System.getProperty('zuzu.model')) &&
+         !model_name.empty?
+        data_dir = case RbConfig::CONFIG['host_os']
+                   when /darwin/
+                     File.join(Dir.home, 'Library', 'Application Support', @app_name || 'Zuzu')
+                   when /mswin|mingw/
+                     File.join(ENV.fetch('APPDATA', Dir.home), @app_name || 'Zuzu')
+                   else
+                     File.join(Dir.home, '.local', 'share', @app_name || 'Zuzu')
+                   end
+        File.join(data_dir, 'models', model_name)
+      else
+        @llamafile_path
+      end
+    end
   end
 
   @config = Config.new

data/lib/zuzu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zuzu
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

data/templates/.claude/skills/add-tool/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: add-tool
+description: Add a new tool that the Zuzu agent can call during conversations. Guides through naming, arguments, implementation, and registers it correctly in app.rb. Use when the developer wants the AI assistant to gain a new capability (e.g. check weather, query a database, read a file, call an API).
+---
+
+# Add a Zuzu Tool
+
+A tool is a Ruby block the agent calls using `<zuzu_tool_call>` tags. Once registered, it is **automatically listed in the agent's system prompt** — no manual prompt editing needed.
+
+## Step 1 — Understand what the tool should do
+
+AskUserQuestion: "What should this tool do? Describe it in one sentence — this description will be shown to the AI agent."
+
+AskUserQuestion: "What arguments does it need? For each: name, type (string/number/boolean), and what it represents. Or 'none' if no arguments."
+
+AskUserQuestion: "Does it need to read/write files (use AgentFS), call an external API, query a database, or just compute something locally?"
+
+## Step 2 — Choose a tool name
+
+- Must be snake_case, descriptive, unambiguous
+- Examples: `get_weather`, `search_notes`, `send_email`, `calculate_tax`, `lookup_stock_price`
+- Check `app.rb` for existing tool names — avoid duplicates
+- AskUserQuestion: "I'll name this tool `<suggested_name>`. Does that work, or would you prefer a different name?"
+
+## Step 3 — Implement the tool
+
+Read `app.rb` to find the insertion point — tools go **between the `Zuzu.configure` block and `Zuzu::App.launch!`**.
+
+### Pattern A — No arguments, no AgentFS
+
+```ruby
+Zuzu::ToolRegistry.register(
+  'tool_name',
+  'One-sentence description shown to the agent.',
+  { type: 'object', properties: {}, required: [] }
+) { |_args, _fs| "result as a string" }
+```
+
+### Pattern B — With arguments
+
+```ruby
+Zuzu::ToolRegistry.register(
+  'tool_name',
+  'Description shown to the agent.',
+  {
+    type: 'object',
+    properties: {
+      param_one: { type: 'string', description: 'what it is' },
+      param_two: { type: 'integer', description: 'what it is' }
+    },
+    required: ['param_one']   # list only truly required params
+  }
+) do |args, _fs|
+  # args keys are STRINGS: args['param_one'] not args[:param_one]
+  value = args['param_one'].to_s
+  "result: #{value}"
+end
+```
+
+### Pattern C — Using AgentFS (sandboxed file/KV access)
+
+```ruby
+Zuzu::ToolRegistry.register(
+  'save_note',
+  'Save a note to the virtual filesystem.',
+  {
+    type: 'object',
+    properties: {
+      title:   { type: 'string', description: 'Note title' },
+      content: { type: 'string', description: 'Note content' }
+    },
+    required: %w[title content]
+  }
+) do |args, fs|
+  # fs is Zuzu::AgentFS — sandboxed, NOT the host filesystem
+  path = "/notes/#{args['title'].downcase.gsub(/\s+/, '_')}.txt"
+  fs.write_file(path, args['content'])
+  "Saved to #{path}"
+end
+```
+
+### Pattern D — Calling an external HTTP API
+
+```ruby
+require 'net/http'
+require 'json'
+
+Zuzu::ToolRegistry.register(
+  'get_weather',
+  'Get current weather for a city using wttr.in.',
+  {
+    type: 'object',
+    properties: {
+      city: { type: 'string', description: 'City name' }
+    },
+    required: ['city']
+  }
+) do |args, _fs|
+  uri = URI("https://wttr.in/#{URI.encode_uri_component(args['city'])}?format=3")
+  Net::HTTP.get(uri).strip
+rescue StandardError => e
+  "Error fetching weather: #{e.message}"
+end
+```
+
+## Step 4 — Enforce these rules before writing
+
+Before inserting code, verify:
+
+- [ ] Tool is placed **before** `Zuzu::App.launch!`
+- [ ] Block signature uses `|args, fs|` or `|args, _fs|` (never zero args)
+- [ ] `args` keys use **string** form: `args['name']` not `args[:name]`
+- [ ] Return value is a **String** (or will be `.to_s`'d automatically)
+- [ ] No `File.read` / `File.write` / `Dir` calls — use `fs` for file access
+- [ ] External HTTP calls have a rescue block returning an error string
+- [ ] Description is one clear sentence (the agent sees this verbatim)
+
+Write the tool to `app.rb` now.
+
+## Step 5 — Verify it loads
+
+```bash
+bundle exec ruby -e "
+require 'zuzu'
+load 'app.rb' rescue nil
+tool = Zuzu::ToolRegistry.find('<tool_name>')
+if tool
+  puts 'Tool registered: ' + tool.name
+  puts 'Description: ' + tool.description
+else
+  puts 'ERROR: tool not found'
+end
+" 2>&1
+```
+
+- If "tool not found": check for syntax errors, verify placement before `launch!`, retry.
+- If syntax error printed: fix it, retry.
+
+## Step 6 — Test in console (if possible without side effects)
+
+```bash
+bundle exec zuzu console
+```
+
+Then in the console:
+```ruby
+store = Zuzu::Store.new
+fs    = Zuzu::AgentFS.new(store)
+tool  = Zuzu::ToolRegistry.find('<tool_name>')
+puts tool.block.call({'param' => 'test_value'}, fs)
+```
+
+- If it returns a sensible result: done.
+- If error: fix and re-verify.
+
+## Step 7 — Tell the user
+
+Show the registered tool code and confirm:
+> ✅ Tool `<name>` registered. The agent will now automatically list it in its system prompt and call it when relevant. Restart the app (`bundle exec zuzu start`) to pick up the change.
+
+If the tool calls an external service that needs configuration (API key, URL, etc.):
+> ⚠️ Remember to set `ENV['YOUR_API_KEY']` or add the value to your configuration before running.