zuzu 0.2.1-java → 0.2.2-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30a4b0d6a387e3fcd5f11779007cca23c75cfc8022e0efaf7b59a51a774f8e9c
-  data.tar.gz: 85912884d1c9a34aea94735f909f9702ecb5e732b09f695e842c5edebab5ccd2
+  metadata.gz: b6098f883dec29f87b5dcece9c69f8e115608cfd89b9cf045fd442355fbf48c9
+  data.tar.gz: d9ffeb971f19158a6262401bdcadb7791bdbd70523c843dd6b7ac26cc3a4c536
 SHA512:
-  metadata.gz: 7df32882674e79a21e55e8f81857eb264c88f168090619ce9af3bda6c356858fd6fda0db17618e808c8b67fd6f3c81e31e14c26857837a96858284b29533ce0b
-  data.tar.gz: 571984d3abb3f76e8afa169fb88257c18441cac52f5e2a085067b2a189af0772e354e0b0c999a73be09cb13365eb3d6c52a98b772717803b5a27fc553fcf099c
+  metadata.gz: b7d6f2d65abfc635d0dceec2122a788d7d2cc03159969c9e06a1b03a45e73eb9c03bf430d5f1a6170a7aaa8c717961bc5c51311336cdf80ab4a3b28feb1dc8b4
+  data.tar.gz: b10535955c154eee0eaade46edb4ee5b1b9049e8e224cea1d49da58553d1bbd1ae263045977f9a1ac6d87dbb5bf0c7da62e26e73eb5ec0c4b3bf8152ba699f58

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`. Users pay, download, double-click, and run. No Docker. No cloud subscription. No infrastructure to maintain. The JVM handles cross-platform distribution the way it has for 30 years.
+
+- **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,15 +295,23 @@ 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.
+
 ---
 
 ## Configuration Reference
@@ -323,6 +337,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'

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,7 +11,7 @@ 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
 
@@ -20,8 +20,9 @@ module Zuzu
       @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

data/lib/zuzu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zuzu
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 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.

data/templates/.claude/skills/customize/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: customize
+description: Customize the Zuzu app — change the app name, window size, system prompt persona, or extend the UI. Use when the developer wants to rebrand the app, add personality to the assistant, or make visual/behavioral changes.
+---
+
+# Customize Zuzu App
+
+Ask what the developer wants to change, then make the changes directly.
+
+## Step 1 — Understand the request
+
+AskUserQuestion: "What would you like to customize? Choose one or more:
+1. App name / window title
+2. Window size
+3. Assistant persona / system prompt instructions
+4. Add a new button or panel to the UI
+5. Something else — describe it"
+
+Route to the relevant section below based on the answer.
+
+---
+
+## Route A — App name and window title
+
+Read the current value from `app.rb`:
+
+```ruby
+Zuzu.configure do |c|
+  c.app_name = 'Current Name'
+```
+
+AskUserQuestion: "What should the app be called?"
+
+Edit `app.rb` — update `c.app_name`. Done. Tell the user to restart the app.
+
+---
+
+## Route B — Window size
+
+Read current values (`c.window_width`, `c.window_height`).
+
+AskUserQuestion: "What size should the window be? (e.g. 1024 × 768, 1280 × 800)"
+
+Edit `app.rb`:
+```ruby
+c.window_width  = 1024
+c.window_height = 768
+```
+
+Done. Tell the user to restart.
+
+---
+
+## Route C — Assistant persona and system prompt
+
+Read the current `c.system_prompt_extras` from `app.rb` (may be nil/absent).
+
+AskUserQuestion: "Describe the assistant's persona or any extra rules you want it to follow. Examples:
+- 'You are a Ruby developer assistant. Always use Ruby in code examples.'
+- 'You are a cooking assistant. Only discuss food, recipes, and nutrition.'
+- 'Always respond concisely in bullet points.'"
+
+AskUserQuestion: "Should this replace the current instructions or be added to them?"
+
+Edit `app.rb` — set or update `c.system_prompt_extras`:
+
+```ruby
+Zuzu.configure do |c|
+  # ...
+  c.system_prompt_extras = <<~EXTRA
+    <the persona instructions here>
+  EXTRA
+end
+```
+
+**Important rules to preserve** — always keep these in `system_prompt_extras` if the developer's text doesn't already cover them:
+- Do not override the tool-calling rules (those come from the base prompt automatically)
+- Keep instructions concise — the model sees this verbatim on every request
+
+Verify it loads:
+```bash
+bundle exec ruby -e "require 'zuzu'; load 'app.rb' rescue nil; puts Zuzu.config.system_prompt_extras" 2>&1
+```
+
+Done. Tell the user to restart.
+
+---
+
+## Route D — UI: add a button to the Admin Panel
+
+The Admin Panel is the popup window opened by the "Admin Panel" button.
+The easiest UI extension is adding a button there.
+
+AskUserQuestion: "What should the button do when clicked?"
+AskUserQuestion: "What label should the button have?"
+
+This requires subclassing `Zuzu::App`. Check if `app.rb` already subclasses it.
+
+**If not subclassing yet**, add this pattern to `app.rb` before `Zuzu::App.launch!`:
+
+```ruby
+class MyApp < Zuzu::App
+  private
+
+  def open_admin_panel
+    file_list_widget = nil
+
+    admin = shell {
+      text 'Admin Panel'
+      minimum_size 380, 500
+      grid_layout 1, false
+
+      label {
+        layout_data(:fill, :fill, true, false)
+        text 'AgentFS — Virtual File Browser'
+        font height: 12, style: :bold
+      }
+
+      file_list_widget = list(:single, :v_scroll, :border) {
+        layout_data(:fill, :fill, true, true)
+        font name: 'Monospace', height: 11
+      }
+
+      # ── Default buttons (keep these) ─────────────────────────
+      button {
+        layout_data(:fill, :fill, true, false)
+        text 'Create Test File'
+        on_widget_selected {
+          @fs.write_file('/test.txt', "Hello!\nCreated at: #{Time.now}")
+          populate_file_list(file_list_widget)
+        }
+      }
+
+      button {
+        layout_data(:fill, :fill, true, false)
+        text 'Clear Chat History'
+        on_widget_selected {
+          @memory.clear
+          message_box { text 'Done'; message 'History cleared.' }.open
+        }
+      }
+
+      button {
+        layout_data(:fill, :fill, true, false)
+        text 'Refresh'
+        on_widget_selected { populate_file_list(file_list_widget) }
+      }
+
+      # ── New custom button ─────────────────────────────────────
+      button {
+        layout_data(:fill, :fill, true, false)
+        text '<Button Label>'
+        on_widget_selected {
+          # your action here
+          message_box { text 'Done'; message 'Action completed.' }.open
+        }
+      }
+    }
+
+    populate_file_list(file_list_widget)
+    admin.open
+  end
+end
+```
+
+Then change the launch line to:
+```ruby
+MyApp.launch!(use_llamafile: true)
+```
+
+**Glimmer DSL rules to enforce:**
+- `layout_data(:fill, :fill, true, false)` — always use argument form, never block form
+- Never call widget methods from a background thread — wrap in `async_exec { }`
+- Never use `sash_form` — invisible on macOS
+
+Verify syntax:
+```bash
+bundle exec ruby -e "require 'zuzu'; load 'app.rb' rescue puts $!.message" 2>&1
+```
+
+Done. Tell the user to restart.
+
+---
+
+## Route E — Something else
+
+Read `AGENTS.md` for the relevant section and implement accordingly.
+Always verify with a syntax check after making changes:
+
+```bash
+bundle exec ruby -e "require 'zuzu'; load 'app.rb' rescue puts $!.message" 2>&1
+```