zephira 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d274d7a5e1cc6ee59747461f1c134e9de1530bf8c323411f497583a0fa474bea
-  data.tar.gz: 6eb27eff2cc6241886e50336fa121caa4499ed35464d7e668a55de9ea38d12d0
+  metadata.gz: 513cf2754ac8c868ab2cb8452a480c8d9cf323b7fbefb629f929afe70aa3ffff
+  data.tar.gz: 6ed7ffcbbbda681d95eeec742c47da212e99ec325d3b72b8c29854e54a4a3dc1
 SHA512:
-  metadata.gz: d41752ccd01be4bcf32df9bc282616784d90a59f6fe3392ebab49623d3c7d8c3a360b16e9c3766a9c5c300fb96deada6ca81f245b4962ded019dd33967464d16
-  data.tar.gz: f5ecfa0bfcfbbe4dd6b260e7f2cf8027f732b4e79c0e8ffe6ed656536357f3e8a498b3586e806ce6afeb1dcb6e6c0cf97cbff1def31f67ded178ed936654b14d
+  metadata.gz: 2d2a968b4a48d35b0e1626e2779f782153acc76fc110887a58d53679b53550e0cb433cb27de3e2895c3a81c65a80bfeae049e3ac632a53393ba6592ba4089b58
+  data.tar.gz: 402f995425bff9f4d759d1184ba2618ef5c19599fc1b5c3983e142426256232c7dcd78255b2f0d20728faff7cf931447c6ea57ae1f92ebd53734121ec5858b9e

data/.dockerignore

@@ -0,0 +1,19 @@
+.DS_Store
+
+coverage
+log
+tmp
+
+.zephira
+.planning
+.claude
+.vendor
+.config
+.cache
+.bundle
+.gem
+.local
+
+.env.dev
+
+*.gem

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Zephira Changelog
 
+## [0.1.4]
+
+### Added
+- First-run onboarding wizard. On a fresh install, Zephira detects that no API key is configured and walks the user through a guided prompt that writes their OpenAI API key to `~/.zephira.yml` (with `0600` permissions). Existing config keys are preserved when merging. Setting `ZEPHIRA_API_KEY` in the environment or running in a non-TTY context bypasses the wizard without prompting.
+- `/reload` slash command. Re-executes the running agent (via `Kernel.exec`) so that local code edits take effect without losing conversation history (which is persisted to `.zephira/history.jsonl`). Routes through `bundle exec` when launched under Bundler, otherwise execs Ruby directly.
+- Podman support. When Docker is unavailable, the sandbox launcher auto-detects Podman and uses it instead.
+- Containerized development helpers under `bin/`: `docker-build` builds the dev image, `docker-shell` runs an interactive bash (or arbitrary command) inside it, and `docker-zephira` launches Zephira against the live mounted workspace. The dev launcher runs the onboarding wizard as a host-side preflight so first-run users get the same experience they'd get from a normal `gem install zephira` invocation.
+
+### Changed
+- README quickstart rewritten — first-run users no longer need to hand-edit `~/.zephira.yml`; the wizard handles it.
+- Dockerfile now bakes Git and ripgrep into the runtime image so in-sandbox tool calls don't have to reinstall them on first use.
+- `.dockerignore` added to trim the build context and stop committed gem artifacts from polluting the runtime image.
+- `*.gem` is now gitignored so locally-built release artifacts are no longer accidentally committed.
+
+### Fixed
+- `code_search` tool now resolves ripgrep correctly inside the sandbox image.
+
+### Tests
+- Suite: 449 examples, 0 failures, ~96% line coverage.
+
 ## [0.1.3]
 
 ### Changed

data/Dockerfile

@@ -8,6 +8,7 @@ RUN apt-get update -qq && \
     apt-get install -y --no-install-recommends \
       build-essential \
       git \
+      ripgrep \
     && rm -rf /var/lib/apt/lists/*
 
 COPY Gemfile Gemfile.lock zephira.gemspec ./
@@ -29,9 +30,16 @@ LABEL org.opencontainers.image.licenses="MIT"
 
 RUN apt-get update -qq && \
     apt-get install -y --no-install-recommends \
+      git \
       libreadline-dev \
+      ripgrep \
     && rm -rf /var/lib/apt/lists/*
 
+RUN groupadd --system zephira && \
+    useradd --system --gid zephira --create-home --shell /bin/bash zephira && \
+    mkdir -p /workspace && \
+    chown zephira:zephira /workspace
+
 COPY --from=deps /usr/local/bundle /usr/local/bundle
 COPY --from=deps /build/zephira-*.gem /tmp/
 
@@ -40,4 +48,6 @@ RUN gem install --local --no-document /tmp/zephira-*.gem && \
 
 WORKDIR /workspace
 
+USER zephira
+
 CMD ["zephira"]

data/README.md

@@ -1,13 +1,32 @@
 # Zephira
 
-Zephira is a command-line AI coding assistant written in Ruby.
+A command-line AI coding assistant written in Ruby. Runs in your terminal, keeps per-project conversation history, and executes safely contained inside a Docker or Podman sandbox by default.
 
-It runs in your terminal, keeps per-project conversation history, calls a pluggable set of tools, and executes inside a Docker sandbox by default so the agent cannot touch the host system unless you opt out. The codebase is small, plugin-based, and intended to be read end-to-end.
+## Quickstart
+
+1. Install Docker or Podman — required for the sandbox.
+   - Docker: https://docs.docker.com/get-docker/
+   - Podman: https://podman.io/getting-started/installation
+
+2. Install the gem:
+
+   ```sh
+   gem install zephira
+   ```
+
+3. Run it from any project directory:
+
+   ```sh
+   zephira
+   ```
+
+   On first run, Zephira launches an onboarding wizard that prompts for your OpenAI API key and writes it to `~/.zephira.yml` (with `0600` permissions). You can also set `ZEPHIRA_API_KEY` in your environment to skip the wizard entirely. To target a different OpenAI-compatible endpoint, set `ZEPHIRA_BASE_URL` alongside your key.
 
 ## Features
 
 - Interactive terminal chat loop with per-session token-budget tracking and automatic history compaction
-- Built-in slash commands: `/help`, `/about`, `/model`, `/history`, `/compact`, `/clear`, `/bye`
+- Built-in slash commands: `/help`, `/about`, `/model`, `/history`, `/compact`, `/clear`, `/reload`, `/bye`
+- First-run onboarding wizard that captures your API key the first time you launch — no manual `~/.zephira.yml` editing required
 - Plugin-style tool system — drop a file in `lib/zephira/tools/` and it is auto-loaded:
   - file I/O: `read_file`, `update_file`, `delete_file`, `list_directory`
   - search: `code_search` (ripgrep-backed), `web_search` (Brave Search API)
@@ -16,25 +35,20 @@ It runs in your terminal, keeps per-project conversation history, calls a plugga
 - Concurrent execution of read-only tool calls in a single turn (mutating tools still run sequentially in declared order)
 - Pluggable model + backend layer — register a new model by dropping a file in `lib/zephira/models/`; backends bind per model class
 - OpenAI-compatible backend out of the box; structured to add provider-specific backends without forking the core loop
-- Docker sandbox enabled by default; `--dangerously-skip-sandbox` to opt out
+- Docker or Podman sandbox enabled by default; `--dangerously-skip-sandbox` to opt out
 - Persistent session log + conversation history under `.zephira/` in each project
 - ~95% line coverage on a focused RSpec suite
 
-## Installation
-
-Requirements:
-
-- Ruby 3.2+
-- Bundler
-- Docker, if you want sandboxed execution
-
-Install from RubyGems:
+## CLI
 
 ```sh
-gem install zephira
+zephira              # start in the current directory
+zephira --help       # CLI help
+zephira --version    # installed version
+zephira --dangerously-skip-sandbox  # run without container isolation (your filesystem is exposed)
 ```
 
-Or install locally for development:
+## Local development install
 
 ```sh
 git clone https://github.com/aarongough/zephira.git
@@ -42,52 +56,22 @@ cd zephira
 bundle install
 ```
 
-## Quick start
-
-Start Zephira in the current project directory:
-
-```sh
-zephira
-```
-
-Show CLI help:
-
-```sh
-zephira --help
-```
-
-Print the installed version:
-
-```sh
-zephira --version
-```
-
-To run without Docker sandboxing:
-
-```sh
-zephira --dangerously-skip-sandbox
-```
-
-Warning: skipping the sandbox gives the agent direct access to your real filesystem.
+Requirements: Ruby 3.2+, Bundler, Docker or Podman (for sandboxed execution).
 
 ## Configuration
 
-Zephira reads configuration from:
+The first time you run Zephira without an API key configured, the onboarding wizard prompts for one and writes it to `~/.zephira.yml`. You can also configure Zephira manually:
 
 - environment variables
 - `.zephira.yml` in the current project
 - `~/.zephira.yml` in your home directory
 
-Environment variables take precedence.
+Environment variables take precedence. Setting `ZEPHIRA_API_KEY` in your environment also skips the onboarding wizard, which is the recommended path for CI and other non-interactive contexts.
 
 Example configuration:
 
 ```yaml
-ZEPHIRA_API_KEY: "your_api_key_here"
-ZEPHIRA_MODEL: "gpt-4.1-mini"
-ZEPHIRA_BASE_URL: "https://api.openai.com/v1"
-ZEPHIRA_BACKEND: "openai_compatible"
-ZEPHIRA_BASE_IMAGE: "ruby:3.4-slim"
+ZEPHIRA_API_KEY: "openai_API_KEY_HERE"
 ZEPHIRA_BRAVE_SEARCH_API_KEY: "your_brave_api_key_here"
 ```
 
@@ -97,17 +81,23 @@ ZEPHIRA_BRAVE_SEARCH_API_KEY: "your_brave_api_key_here"
 - `ZEPHIRA_MODEL` — model name to use
 - `ZEPHIRA_BASE_URL` — base URL for OpenAI-compatible APIs
 - `ZEPHIRA_BACKEND` — backend adapter identifier
-- `ZEPHIRA_BASE_IMAGE` — base Docker image for sandbox execution
+- `ZEPHIRA_BASE_IMAGE` — base container image for sandbox execution
 - `ZEPHIRA_BRAVE_SEARCH_API_KEY` — required for the web search tool
 - `ZEPHIRA_SANDBOX` — internal/advanced flag to disable sandboxing
 
 ## Sandbox behavior
 
-By default, Zephira attempts to run inside Docker for safer execution.
+By default, Zephira attempts to run inside a container for safer execution.
+
+When sandboxing is enabled, Zephira re-executes itself inside Docker or Podman and mounts your current project into `/workspace`. This gives the agent access to the project while helping isolate it from the host system.
+
+To keep files created or edited in `/workspace` owned by the host user instead of root, Zephira runs the sandboxed process as your current host UID/GID at container runtime.
 
-When sandboxing is enabled, Zephira re-executes itself inside a container and mounts your current project into `/workspace`. This gives the agent access to the project while helping isolate it from the host system.
+Zephira also mounts your global config into a sandbox-specific home directory inside the container so the agent can read `~/.zephira.yml` and `~/.zephira/` without depending on `/root`.
 
-If Docker is unavailable, Zephira exits with an error and explains how to proceed.
+Zephira prefers Docker when both Docker and Podman are available. If Docker is unavailable but Podman is available, Zephira uses Podman automatically.
+
+If neither Docker nor Podman is available, Zephira exits with an error and explains how to proceed.
 
 You can bypass sandboxing with:
 
@@ -128,8 +118,11 @@ Inside Zephira, you can use slash commands:
 - `/history` — print conversation history
 - `/compact` — manually compact the conversation history
 - `/clear` — clear the screen
+- `/reload` — re-execute the agent process to pick up local code changes (conversation history is preserved)
 - `/bye` — exit the session
 
+To change your API key after onboarding, edit `~/.zephira.yml` directly on the host, or delete it and re-launch to trigger the wizard again.
+
 ## Available models
 
 This repository currently includes model definitions for:
@@ -196,6 +189,26 @@ Run linting:
 bundle exec standardrb --fix
 ```
 
+### Containerized development
+
+For an isolated dev environment that mirrors the shipped sandbox image, the `bin/` directory provides helper scripts. All three rebuild the `zephira-dev` image first (Docker caches layers, so this is a no-op after the first run).
+
+- `bin/docker-build` — build the `zephira-dev` image from the current working tree.
+- `bin/docker-zephira` — launch Zephira inside the container, running against the mounted working tree (`bundle exec ruby exe/zephira`). Use this when iterating on the agent itself.
+- `bin/docker-shell [command]` — start an interactive `bash` inside the container, or run an arbitrary command. Useful for running specs or linting against the containerized Ruby:
+
+  ```sh
+  bin/docker-shell                                # interactive shell
+  bin/docker-shell 'bundle exec rspec'            # run the suite in-container
+  bin/docker-shell 'bundle exec standardrb --fix' # lint in-container
+  ```
+
+Both runner scripts mount the current directory at `/workspace`, run as the host UID/GID, and mount `~/.zephira.yml` and `~/.zephira/` into the container so configuration and history persist across runs.
+
+`bin/docker-zephira` runs the onboarding wizard as a host-side preflight before launching the container, so first-run users get the same prompt-and-write-to-`~/.zephira.yml` experience they'd get with a normal `gem install zephira` invocation.
+
+While inside a running Zephira session started this way, the `/reload` slash command re-executes the agent process — picking up edits to `lib/zephira/**` without rebuilding the image or losing conversation history (which is persisted to `.zephira/history.jsonl`). This is the fastest inner loop for iterating on agent code.
+
 ## Design goals
 
 Zephira favors:

data/exe/zephira

@@ -3,4 +3,5 @@
 
 require "zephira"
 
+Zephira::ORIGINAL_ARGV = ARGV.dup.freeze
 Zephira::CLI.new(ARGV)

data/lib/zephira/agent.rb

@@ -40,6 +40,19 @@ module Zephira
       You should not try to guess what the user is trying to do, or try to
       perform operations that are not explicitly requested by the user.
 
+      When investigating a bug, failure, or unexpected behavior:
+        - Do not speculate when the relevant code can be inspected.
+        - Read the implementation and the nearest calling code before answering.
+        - Prefer tracing the full execution path over making a local guess from one file.
+        - Reproduce the issue when feasible.
+        - Identify the most likely root cause from evidence, not intuition.
+        - If the issue appears to be caused by your recent changes, fix it immediately.
+        - After making a fix, run the narrowest useful test first, then the full spec suite and the linter before declaring completion.
+        - If you cannot complete validation, state exactly what blocked you and the next concrete command to run.
+        - Do not stop at partial diagnosis when the next investigative step is obvious and feasible.
+
+      Before replying on debugging or regression tasks, exhaust the obvious local investigation steps available in the repository and runtime environment. Prefer one evidence-backed answer over several speculative possibilities.
+
       Additional instructions provided by the user. The project-local instructions
       should overrule the global instructions:
 
@@ -55,7 +68,7 @@ module Zephira
       The user's current `ls -R` is: @@@LSR@@@
     PROMPT
 
-    LOGO = <<~'LOGO'
+    LOGO = <<~LOGO
       ░▒▓████████▓▒░░▒▓████████▓▒░░▒▓███████▓▒░ ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓███████▓▒░  ░▒▓██████▓▒░
            ░▒▓██▓▒░ ░▒▓█▓▒░       ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░
          ░▒▓██▓▒░   ░▒▓██████▓▒░  ░▒▓███████▓▒░ ░▒▓████████▓▒░░▒▓█▓▒░░▒▓███████▓▒░ ░▒▓████████▓▒░
@@ -93,7 +106,7 @@ module Zephira
     def thinking(model_class)
       thinkmojis = %w[🤔 🧠 💭 🤯 🧐 ⏳ 🔄 🌀 🤨 💡 🧩 🔍 📚 ⚙️]
       token_count = Tokens.estimate(history.messages.to_json)
-      update_status("Thinking... #{thinkmojis.shuffle.first} " + Formatter.color(:grey, "(#{model_class.model_name} - #{token_count} tokens)"))
+      update_status("Thinking... #{thinkmojis.sample} " + Formatter.color(:grey, "(#{model_class.model_name} - #{token_count} tokens)"))
     end
 
     def update_status(msg)
@@ -202,8 +215,8 @@ module Zephira
       print TTY::Cursor.move_to(0, screen_height - 3)
       puts Formatter.color(:grey, "-" * width)
 
-      sandbox_label = ENV["ZEPHIRA_IN_SANDBOX"] == "1" ? "sandboxed" : "⚠ DANGER: NO SANDBOX"
-      sandbox_color = ENV["ZEPHIRA_IN_SANDBOX"] == "1" ? :green : :red
+      sandbox_label = (ENV["ZEPHIRA_IN_SANDBOX"] == "1") ? "sandboxed" : "⚠ DANGER: NO SANDBOX"
+      sandbox_color = (ENV["ZEPHIRA_IN_SANDBOX"] == "1") ? :green : :red
       right_text = "ctrl+c to exit | '/help' + enter to see commands | #{context_pct}% context left"
       padding = [width - sandbox_label.length - right_text.length, 1].max
       puts Formatter.color(sandbox_color, sandbox_label) + " " * padding + Formatter.color(:grey, right_text)

data/lib/zephira/cli.rb

@@ -8,8 +8,9 @@ module Zephira
 
     def initialize(argv)
       ENV["ZEPHIRA_SANDBOX"] = "false" if argv.include?(DANGEROUS_SKIP_SANDBOX_FLAG)
-      Zephira::Sandbox.exec_if_needed!(argv)
       option_parser.parse!(argv)
+      Zephira::Onboarding.run_if_needed!
+      Zephira::Sandbox.exec_if_needed!(argv)
       Zephira::Agent.new.run_loop
     rescue OptionParser::InvalidOption
       puts option_parser

data/lib/zephira/commands/reload.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Commands
+    class Reload
+      class << self
+        def name
+          "reload"
+        end
+
+        def description
+          "Reload the agent by re-executing the process (picks up code changes)"
+        end
+
+        def run(agent:, args:)
+          puts "Reloading…"
+          argv = defined?(::Zephira::ORIGINAL_ARGV) ? ::Zephira::ORIGINAL_ARGV : []
+          if ENV["BUNDLE_GEMFILE"] && File.exist?(ENV["BUNDLE_GEMFILE"])
+            Kernel.exec("bundle", "exec", RbConfig.ruby, $PROGRAM_NAME, *argv)
+          else
+            Kernel.exec(RbConfig.ruby, $PROGRAM_NAME, *argv)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zephira/completions/file_names.rb

@@ -14,7 +14,7 @@ module Zephira
         end
 
         Dir.glob(pattern).map do |path|
-          "@#{path}#{File.directory?(path) ? "/" : ""}"
+          "@#{path}#{"/" if File.directory?(path)}"
         end
       end
     end

data/lib/zephira/onboarding.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "yaml"
+
+module Zephira
+  class Onboarding
+    GLOBAL_CONFIG_PATH = File.expand_path("~/.zephira.yml")
+
+    OUTER_TL = "╔"
+    OUTER_TR = "╗"
+    OUTER_BL = "╚"
+    OUTER_BR = "╝"
+    OUTER_H = "═"
+    OUTER_V = "║"
+
+    class << self
+      def run_if_needed!
+        return if ENV["ZEPHIRA_IN_SANDBOX"] == "1"
+        return unless Config.read("ZEPHIRA_API_KEY").to_s.empty?
+
+        unless $stdin.tty?
+          print_no_tty_error
+          exit(1)
+        end
+
+        print_welcome
+        key = prompt_key
+        if key.nil? || key.empty?
+          print_cancelled
+          exit(1)
+        end
+
+        write_config!(key)
+        print_success
+      end
+
+      private
+
+      def prompt_key
+        print "  OpenAI API key: "
+        raw = $stdin.noecho(&:gets)
+        puts
+        return nil if raw.nil?
+        stripped = raw.strip
+        stripped.empty? ? nil : stripped
+      rescue Interrupt
+        puts
+        nil
+      end
+
+      def write_config!(key)
+        existing = File.exist?(GLOBAL_CONFIG_PATH) ? (YAML.load_file(GLOBAL_CONFIG_PATH) || {}) : {}
+        merged = existing.merge("ZEPHIRA_API_KEY" => key)
+        File.write(GLOBAL_CONFIG_PATH, YAML.dump(merged))
+        File.chmod(0o600, GLOBAL_CONFIG_PATH)
+      end
+
+      def print_welcome
+        lines = [
+          "",
+          "  #{Formatter.color(:green, Formatter.style(:bold, "Welcome to Zephira"))}",
+          "",
+          "  Zephira talks to OpenAI by default. Paste your OpenAI API key below",
+          "  and we'll save it to ~/.zephira.yml for future runs.",
+          "",
+          "  To target a different OpenAI-compatible endpoint instead, cancel and",
+          "  set ZEPHIRA_BASE_URL alongside your key in ~/.zephira.yml.",
+          "",
+          "  Input is hidden. Press Enter on an empty line to cancel.",
+          ""
+        ]
+        render_box(lines, :green)
+        puts
+      end
+
+      def print_success
+        puts
+        puts "  #{Formatter.color(:green, "✓")} Saved API key to #{GLOBAL_CONFIG_PATH}"
+        puts
+      end
+
+      def print_cancelled
+        puts
+        puts "  #{Formatter.color(:grey, "Cancelled.")} Set ZEPHIRA_API_KEY in your environment"
+        puts "  or populate ~/.zephira.yml to skip onboarding."
+        puts
+      end
+
+      def print_no_tty_error
+        warn ""
+        warn "  #{Formatter.color(:red, "ERROR:")} Zephira needs an OpenAI API key, but stdin is not a TTY."
+        warn ""
+        warn "  Set ZEPHIRA_API_KEY in your environment, or populate"
+        warn "  ~/.zephira.yml with:"
+        warn ""
+        warn "    ZEPHIRA_API_KEY: \"sk-...\""
+        warn ""
+      end
+
+      def render_box(lines, color)
+        width = box_width(lines)
+        puts Formatter.color(color, OUTER_TL + OUTER_H * (width - 2) + OUTER_TR)
+        lines.each { |line| puts box_row(line, width, color) }
+        puts Formatter.color(color, OUTER_BL + OUTER_H * (width - 2) + OUTER_BR)
+      end
+
+      def box_row(text, width, color)
+        padding = " " * [width - 2 - visible_length(text), 0].max
+        Formatter.color(color, OUTER_V) + text + padding + Formatter.color(color, OUTER_V)
+      end
+
+      def box_width(lines)
+        content_max = lines.map { |line| visible_length(line) }.max || 0
+        desired = content_max + 4
+        [desired, terminal_width].min.then { |target| [target, content_max + 4].max }
+      end
+
+      def visible_length(str)
+        str.gsub(/\e\[[0-9;]*m/, "").length
+      end
+
+      def terminal_width
+        IO.console&.winsize&.last || 80
+      rescue
+        80
+      end
+    end
+  end
+end

data/lib/zephira/sandbox.rb

@@ -5,8 +5,10 @@ require "io/console"
 
 module Zephira
   class Sandbox
-    GHCR_IMAGE           = "ghcr.io/aarongough/zephira"
+    GHCR_IMAGE = "ghcr.io/aarongough/zephira"
     DERIVED_IMAGE_PREFIX = "zephira-sandbox"
+    CONTAINER_RUNTIMES = %w[docker podman].freeze
+    SANDBOX_HOME = "/tmp/zephira-home"
 
     FORWARDED_ENV_PATTERNS = [/\AZEPHIRA_/].freeze
     FORWARDED_ENV_EXCLUDES = %w[ZEPHIRA_IN_SANDBOX ZEPHIRA_SANDBOX].freeze
@@ -15,15 +17,15 @@ module Zephira
     OUTER_TR = "╗"
     OUTER_BL = "╚"
     OUTER_BR = "╝"
-    OUTER_H  = "═"
-    OUTER_V  = "║"
+    OUTER_H = "═"
+    OUTER_V = "║"
 
     INNER_TL = "┌"
     INNER_TR = "┐"
     INNER_BL = "└"
     INNER_BR = "┘"
-    INNER_H  = "─"
-    INNER_V  = "│"
+    INNER_H = "─"
+    INNER_V = "│"
     INNER_PADDING = 3
 
     class << self
@@ -31,11 +33,12 @@ module Zephira
         return if ENV["ZEPHIRA_IN_SANDBOX"] == "1"
         return if ENV["ZEPHIRA_SANDBOX"] == "false"
 
-        abort_with_sandbox_error unless docker_available?
+        runtime = container_runtime
+        abort_with_sandbox_error unless runtime
 
-        target = resolve_image
-        $stderr.puts "[Zephira] Launching in Docker sandbox (#{target})..."
-        Kernel.exec(*build_docker_command(argv, target))
+        target = resolve_image(runtime)
+        warn "[Zephira] Launching in #{runtime.capitalize} sandbox (#{target})..."
+        Kernel.exec(*build_container_command(argv, target, runtime))
       end
 
       private
@@ -54,12 +57,15 @@ module Zephira
 
         instruction_lines = [
           "",
-          "  #{Formatter.color(:red, "ERROR:")} Zephira requires Docker to run safely in a sandboxed environment.",
+          "  #{Formatter.color(:red, "ERROR:")} Zephira requires Docker or Podman to run safely in a sandboxed",
+          "  environment.",
           "",
-          "  Docker was not found or is not currently running. To fix this:",
+          "  Neither Docker nor Podman was found or currently running. To fix this:",
           "",
           "    1. Install Docker Desktop:  https://docs.docker.com/get-docker/",
-          "    2. Start Docker and confirm it is running:  docker info",
+          "       or install Podman:      https://podman.io/getting-started/installation",
+          "    2. Start the runtime and confirm it is running:",
+          "       docker info   or   podman info",
           "",
           "  To bypass the sandbox (not recommended):",
           "",
@@ -67,9 +73,9 @@ module Zephira
           ""
         ]
 
-        max_warn_width    = warn_lines.map { |line| visible_length(line) }.max
+        max_warn_width = warn_lines.map { |line| visible_length(line) }.max
         max_content_width = instruction_lines.map { |line| visible_length(line) }.max
-        inner_width       = [max_warn_width, max_content_width - 10].max
+        inner_width = [max_warn_width, max_content_width - 10].max
 
         inner_box = [
           "  " + inner_top(inner_width),
@@ -84,7 +90,7 @@ module Zephira
           *content.map { |line| outer_row(line, width) },
           outer_bottom(width),
           ""
-        ].each { |line| $stderr.puts line }
+        ].each { |line| warn line }
         exit(1)
       end
 
@@ -121,22 +127,26 @@ module Zephira
 
       def terminal_width
         IO.console&.winsize&.last || 80
-      rescue StandardError
+      rescue
         80
       end
 
-      def docker_available?
-        system("docker info > /dev/null 2>&1")
+      def runtime_available?(binary)
+        system("#{binary} info > /dev/null 2>&1")
       end
 
-      def resolve_image
+      def container_runtime
+        CONTAINER_RUNTIMES.find { |runtime| runtime_available?(runtime) }
+      end
+
+      def resolve_image(runtime)
         base = Config.read("ZEPHIRA_BASE_IMAGE")
         return "#{GHCR_IMAGE}:#{VERSION}" unless base
 
         derived = derived_image_name(base)
-        unless image_exists?(derived)
-          $stderr.puts "[Zephira] Building sandbox image from #{base}..."
-          build_derived_image(base, derived)
+        unless image_exists?(derived, runtime)
+          warn "[Zephira] Building sandbox image from #{base} with #{runtime}..."
+          build_derived_image(base, derived, runtime)
         end
         derived
       end
@@ -146,16 +156,16 @@ module Zephira
         "#{DERIVED_IMAGE_PREFIX}-#{sanitized}:#{VERSION}"
       end
 
-      def image_exists?(name)
-        system("docker image inspect #{name} > /dev/null 2>&1")
+      def image_exists?(name, runtime)
+        system("#{runtime} image inspect #{name} > /dev/null 2>&1")
       end
 
-      def build_derived_image(base_image, target_name)
+      def build_derived_image(base_image, target_name, runtime)
         dockerfile = "FROM #{base_image}\nRUN gem install zephira:#{VERSION} --no-document\n"
         Tempfile.create(["zephira-sandbox", ".dockerfile"]) do |file|
           file.write(dockerfile)
           file.flush
-          system("docker build -t #{target_name} -f #{file.path} .")
+          system("#{runtime} build -t #{target_name} -f #{file.path} .")
         end
       end
 
@@ -166,18 +176,21 @@ module Zephira
           .sort
       end
 
-      def build_docker_command(argv, image)
-        cmd = ["docker", "run", "--rm", "-i"]
+      def build_container_command(argv, image, runtime)
+        cmd = [runtime, "run", "--rm", "-i"]
         cmd << "-t" if $stdout.tty?
 
+        cmd += ["--user", "#{Process.uid}:#{Process.gid}"]
         cmd += ["-e", "ZEPHIRA_IN_SANDBOX=1"]
+        cmd += ["-e", "HOME=#{SANDBOX_HOME}"]
         cmd += ["-v", "#{Dir.pwd}:/workspace:rw"]
+        cmd += ["-v", "#{sandbox_home_mount(runtime)}:#{SANDBOX_HOME}:rw"]
 
         global_config = File.expand_path("~/.zephira.yml")
-        cmd += ["-v", "#{global_config}:/root/.zephira.yml:ro"] if File.exist?(global_config)
+        cmd += ["-v", "#{global_config}:#{SANDBOX_HOME}/.zephira.yml:ro"] if File.exist?(global_config)
 
         global_dir = File.expand_path("~/.zephira")
-        cmd += ["-v", "#{global_dir}:/root/.zephira:ro"] if File.exist?(global_dir) && File.directory?(global_dir)
+        cmd += ["-v", "#{global_dir}:#{SANDBOX_HOME}/.zephira:ro"] if File.exist?(global_dir) && File.directory?(global_dir)
 
         forwarded_env_keys.each do |key|
           cmd += ["-e", "#{key}=#{ENV[key]}"]
@@ -188,6 +201,12 @@ module Zephira
         cmd += ["zephira"] + argv
         cmd
       end
+
+      def sandbox_home_mount(runtime)
+        return "zephira-home-#{Process.uid}" if runtime == "docker"
+
+        File.expand_path("~/.zephira/sandbox-home")
+      end
     end
   end
 end

data/lib/zephira/tokens.rb

@@ -6,7 +6,7 @@ module Zephira
   # which lands within ~20% of real BPE tokenizers (GPT/Claude) for English
   # text — close enough for context-budget decisions, never trust for billing.
   module Tokens
-    TOKEN_PATTERN = /\w+|[^\s\w]/.freeze
+    TOKEN_PATTERN = /\w+|[^\s\w]/
 
     def self.estimate(text)
       return 0 if text.nil? || text.empty?

data/lib/zephira/tools/code_search.rb

@@ -127,8 +127,12 @@ module Zephira
       end
 
       def executable_available?(cmd)
-        _, _, status = Open3.capture3("command", "-v", cmd)
-        status.success?
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |directory|
+          next false if directory.nil? || directory.empty?
+
+          executable = File.join(directory, cmd)
+          File.file?(executable) && File.executable?(executable)
+        end
       end
     end
   end

data/lib/zephira/tools/web_search.rb

@@ -77,7 +77,7 @@ module Zephira
           return error_result(message: "`query` must be a non-empty string")
         end
 
-        if num_results && (!num_results.is_a?(Integer) || !(1..50).include?(num_results))
+        if num_results && (!num_results.is_a?(Integer) || !(1..50).cover?(num_results))
           return error_result(message: "`num_results` must be an integer between 1 and 50")
         end
 

data/lib/zephira/tools.rb

@@ -45,8 +45,7 @@ module Zephira
     end
 
     def read_only?(name)
-      tool = constants.find { |candidate| candidate.name == name }
-      tool && tool.respond_to?(:read_only?) && tool.read_only?
+      constants.find { |candidate| candidate.name == name }&.read_only?
     end
 
     def find!(name)

data/lib/zephira/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zephira
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/lib/zephira.rb

@@ -4,6 +4,7 @@ require_relative "zephira/version"
 require_relative "zephira/config"
 require_relative "zephira/sandbox"
 require_relative "zephira/formatter"
+require_relative "zephira/onboarding"
 require_relative "zephira/tokens"
 require_relative "zephira/logger"
 require_relative "zephira/backends"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zephira
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Aaron Gough
@@ -158,6 +158,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".dockerignore"
 - ".rspec"
 - CHANGELOG.md
 - Dockerfile
@@ -178,6 +179,7 @@ files:
 - lib/zephira/commands/help.rb
 - lib/zephira/commands/history.rb
 - lib/zephira/commands/model.rb
+- lib/zephira/commands/reload.rb
 - lib/zephira/completions.rb
 - lib/zephira/completions/file_names.rb
 - lib/zephira/completions/slash_commands.rb
@@ -194,6 +196,7 @@ files:
 - lib/zephira/models/gpt_5_5.rb
 - lib/zephira/models/gpt_o4_mini.rb
 - lib/zephira/models/llama4.rb
+- lib/zephira/onboarding.rb
 - lib/zephira/sandbox.rb
 - lib/zephira/tokens.rb
 - lib/zephira/tools.rb
@@ -214,7 +217,6 @@ files:
 - lib/zephira/version.rb
 - license.txt
 - standard.yml
-- zephira-0.1.0.gem
 homepage: https://github.com/aarongough/zephira
 licenses:
 - MIT