llm.rb 13.0.0 → 13.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0304f2a840c94209256729edf114209ffab0bdd309d1a25172818458e4c3f4f
-  data.tar.gz: 46c695d1722ef6e618f27eb9b433f77774bf9140bfd31983589946be3ce53c1e
+  metadata.gz: bb5c6136080e0136309987a4e042e6f646c26de39e38d6422bb3904fc665bf5f
+  data.tar.gz: d832b9c19f4173ba6e5631ffdc57f495eb4a9a8fb0b657801de185707bc4085e
 SHA512:
-  metadata.gz: 0a9da53406a6e612f68412005d33b0e85bf6064c9c38ff70e5cd2290f8b381bbba9ae9becd6ca71b15fed399e1d84bdd55972301d0cdb51c10d528d00f5a5d8f
-  data.tar.gz: 882a041334ad21b83397792e3921510c0298b0c623b6c05441117f5655ac1fbe35b560cb015b29bcbd0aad526cc772d9e58596567c72d456d3ee77adc372f397
+  metadata.gz: 7ba4417a8c5b48a28b2baf04a2960374eae28c44dc2ec19e8f79da9a95f75fdf8cb5f1c749e6bfa1b1f6d1c790723e2005cb576f94f118997bb5e8b0f5d53a63
+  data.tar.gz: 0105af6bcaaec50930546e3a5a7207b8cf65e30bbea33359784061159748a3e2f3afb6e2b599eaad904e0c477d9827bb444c698315e56d43572be6ba86fe98b8

data/CHANGELOG.md

@@ -15,7 +15,178 @@
 
 ## What's next
 
-_No unreleased changes yet._
+*No unreleased changes yet. Check back after the next release.*
+
+## v13.1.0
+
+Changes since `v13.0.0`.
+
+This release adds `LLM::Agent` class DSL attributes (`path`, `description`),
+extends skills with file-path loading and the `tools: all` directive, adds new
+built-in tools (`LLM::Tool::Ruby`, `LLM::Tool::EditFile`), introduces the
+`LLM::Tracer::PrettyLogger` for human-readable tracing, renames `Transcript`
+to `Buffer` across the REPL, ships a `bin/llm.rb` CLI entry point, and fixes
+several agent and tool bugs around persistence, interruption, and naming.
+
+### Core
+
+* **add post install message with deepdive link** <br>
+  The gemspec now includes a `post_install_message` that points users to
+  the deepdive guide at `https://r.uby.dev/llm/deepdive` after installation,
+  making it easier for new users to discover the project documentation.
+
+### Agent
+
+* **add `description` class DSL and instance method** <br>
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) now
+  has a `description` class DSL (`description "release engineer"`) and a
+  corresponding `#description` instance method. The description is an
+  optional self-documenting string that serves as a brief summary of the
+  agent's purpose. It can be set via the class DSL,
+  `LLM::Agent.set(description: ...)`, or `LLM::Agent.new(description: ...)`.
+
+* **add `path` class DSL and instance method** <br>
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) now
+  has a `path` class DSL (`path "contexts/admin.json"`) and a
+  corresponding `#path` instance method. When a path is set, the agent
+  automatically restores its conversation history from that file on
+  initialization and saves it back after each `talk` or `ask` turn,
+  making session persistence across process restarts transparent.
+
+### Skills
+
+* **accept a path to a markdown file** <br>
+  [`LLM::Skill.load`](https://r.uby.dev/api-docs/llm.rb/LLM/Skill.html#load-class_method)
+  now accepts a path to a markdown file in addition to a directory path.
+  When given a file path, the file is read directly instead of looking for
+  a `SKILL.md` inside a directory. This makes it possible to load a single
+  markdown file as a skill without placing it in a dedicated directory.
+
+* **extend with `all` keyword for loading the full tool registry** <br>
+  `LLM::Skill` now supports `tools: all` (or `tools: "*"`) in the frontmatter
+  to load all tools from the global
+  [`LLM::Tool.registry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#registry-class_method).
+  Previously, the `tools:` frontmatter only accepted `inherit`, an array of tool
+  names, or nothing. The new `all` keyword makes it possible to give a skill
+  access to every registered tool without listing them individually.
+
+### Tools
+
+* **add `LLM::Tool::Ruby` for executing Ruby code in a subprocess** <br>
+  [`LLM::Tool::Ruby`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Ruby.html)
+  is a new built-in tool that runs a string of Ruby code in a separate
+  Ruby process with a configurable timeout (default 15s). The code runs
+  in an isolated address space unaware of its parent, making it useful
+  for safe(ish) dynamic code execution. It must be required explicitly
+  with `require "llm/tools/ruby"` and requires the `test-cmd.rb` gem.
+
+* **rename `LLM::Tool::SwapText` to `LLM::Tool::EditFile`** <br>
+  The `SwapText` tool has been renamed to
+  [`LLM::Tool::EditFile`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/EditFile.html)
+  to better match the naming of sibling tools (`ReadFile`, `WriteFile`).
+  The old `require "llm/tools/swap_text"` path no longer exists; use
+  `require "llm/tools/edit-file"` instead.
+
+### Tracer
+
+* **add `LLM::Tracer::PrettyLogger` for human-readable tracing** <br>
+  [`LLM::Tracer::PrettyLogger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/PrettyLogger.html)
+  is a new tracer that writes human-readable request and tool-call logs to a
+  console or file. Unlike the structured JSON output of
+  `LLM::Tracer::Logger`, the pretty logger emits single-line entries with
+  inline context, making it easier to follow agent activity at a glance.
+  It writes to `$stderr` by default and accepts an `io:` option for file
+  output.
+
+### Repl
+
+* **rename `LLM::Repl::Transcript` to `LLM::Repl::Buffer`** <br>
+  `LLM::Repl::Transcript` has been renamed to
+  [`LLM::Repl::Buffer`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Buffer.html)
+  to better reflect its role as a conversation state manager. The old
+  `start` and `finish` methods have been renamed to `open` and `close`
+  respectively. The public accessor on
+  [`LLM::Repl`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl.html) has been
+  renamed from `transcript` to `buffer`.
+
+* **add `write_message` for formatted message writing** <br>
+  [`LLM::Repl::Buffer#write_message`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Buffer.html#write_message-instance_method)
+  and
+  [`LLM::Repl#write_message`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl.html#write_message-instance_method)
+  provide a convenience method that takes a username and content string,
+  formatting the output with a bold `user:` label and a trailing newline.
+  This is simpler than the equivalent sequence of `write` calls.
+
+* **add `Command#write_message` and refactor `Command#write`** <br>
+  [`LLM::Command#write_message`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Command.html#write_message-instance_method)
+  provides a convenience method that takes a username and content string,
+  matching the same interface on `LLM::Repl` and `LLM::Buffer`. The
+  `Command#write` method is now implemented on top of `write_message`,
+  always prefixing output with `command(<name>): `. The `who:` keyword
+  argument previously accepted by `write` has been removed; use
+  `write_message` instead.
+
+* **display pre-existing agent messages when the repl starts** <br>
+  When
+  [`LLM::Agent#repl`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
+  starts, any messages already in the agent's buffer are now rendered
+  in the REPL window. Previously the REPL started with an empty
+  transcript even when the agent carried prior conversation history,
+  making it harder to resume a session. Tool-call and tool-return
+  messages are skipped to avoid visual noise.
+
+### CLI
+
+* **add `bin/llm.rb` for launching the REPL from the command line** <br>
+  A new executable script (`bin/llm.rb`) provides a convenient way to start
+  an interactive REPL session directly from the terminal. It auto-detects
+  the provider from environment variables like `OPENAI_API_KEY`, supports
+  a `-p PROVIDER` flag for explicit provider selection, a `-t` flag for
+  temporary (non-persistent) sessions, and `-h` for help. Sessions are
+  automatically saved to `~/.llm.rb/` by default.
+
+### Fix
+
+* **agent: fix `path` restore on first run** <br>
+  Fix a bug where [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
+  called `@ctx.restore(path:)` even when the path's file did not exist.
+  The fix checks `File.readable?(@path)` before attempting to restore,
+  so the agent starts with a blank conversation on first use instead of
+  failing with a file-not-found error.
+
+* **tools: re-raise `LLM::Interrupt` to abort the turn** <br>
+  [`LLM::Tool::Git`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Git.html),
+  [`LLM::Tool::Mkdir`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Mkdir.html),
+  [`LLM::Tool::Rg`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Rg.html),
+  [`LLM::Tool::Ruby`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Ruby.html),
+  and
+  [`LLM::Tool::Shell`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Shell.html)
+  now re-raise `LLM::Interrupt` after killing their running command. The
+  previous behavior rescued the interrupt and killed the child process but
+  let the turn continue, which meant a cancelled tool call did not abort
+  the conversation turn. Re-raising ensures the entire turn is interrupted.
+
+* **tools: rescue `LLM::Interrupt` in shell-based tools** <br>
+  [`LLM::Tool::Shell`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Shell.html),
+  [`LLM::Tool::Git`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Git.html),
+  [`LLM::Tool::Mkdir`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Mkdir.html),
+  and
+  [`LLM::Tool::Rg`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Rg.html)
+  now rescue `LLM::Interrupt` and kill their running command, preventing
+  orphaned child processes when a tool is interrupted during execution.
+
+* **agent: fix default name derivation** <br>
+  Fix a bug where `LLM::Agent` used without a subclass derived its default
+  name as `"l-lm-agent"` instead of `"agent"`. The fix replaces the
+  regex-based parameterization with a pattern that correctly handles
+  single-word class names and multi-word namespaced names.
+
+* **function: `#params` always returns an `LLM::Object`** <br>
+  [`LLM::Function#params`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#params-instance_method)
+  now always returns an `LLM::Object` representing the function's parameter
+  schema. Previously it returned `nil` when a function defined no parameters,
+  forcing every caller to guard against `nil`. All provider adapters now use
+  `fn.params.to_h` instead of `fn.params || {type: "object", properties: {}}`.
 
 ## v13.0.0
 
@@ -406,7 +577,7 @@ reliable across all six concurrency backends. The `functions` and
 
 Changes since `v12.5.1`.
 
-This release adds bulk defaults for tools and agents — `LLM::Tool.defaults`
+This release adds bulk defaults for tools and agents: `LLM::Tool.defaults`
 for setting parameter defaults and `LLM::Agent.set` for mass-assigning
 class-level defaults, both mirrored on ActiveRecord and Sequel agent models.
 
@@ -442,7 +613,7 @@ prior call.
   On cancel, `LLM::Interrupt` is now raised on the thread that is
   running a tool. The tool can rescue `LLM::Interrupt` and gracefully
   terminate (e.g., clean up resources). The previous approach used
-  `Thread#interrupt` which was less reliable — it did not interrupt a
+  `Thread#interrupt` which was less reliable. It did not interrupt a
   sleeping thread.
 
 * **function: suppress thread exception reporting in `:thread` concurrency** <br>
@@ -468,15 +639,15 @@ prior call.
   `LLM::Interrupt` is now raised on the active fiber via `Fiber#raise`
   when interrupting `:fiber`-concurrency tools.
   <br><br>
-  `Task#interrupt!` now dispatches by task type — `Thread#raise` for
-  threads, `Fiber#raise` for fibers — making interruption reliable
+  `Task#interrupt!` now dispatches by task type: `Thread#raise` for
+  threads, `Fiber#raise` for fibers. Making interruption reliable
   across all concurrency strategies.
 
 * **function: raise `LLM::Interrupt` on fork-backed tool tasks** <br>
   `LLM::Interrupt` is now raised on the main thread of a fork child
   process via `Thread.main.raise(LLM::Interrupt)` when interrupting
   `:fork`-concurrency tools, and the fork `Task#wait` re-raises the
-  interrupt on the parent side — making interruption reliable across
+  interrupt on the parent side. Making interruption reliable across
   all concurrency strategies including `:fork`.
 
 * **function: raise `LLM::Interrupt` on `Async::Task`-backed tool tasks** <br>
@@ -494,7 +665,7 @@ prior call.
   raises `LLM::Interrupt` on the ractor's main thread.
   <br><br>
   `Task#interrupt!` delegates to the mailbox to send the interrupt
-  message — extending reliable interruption to the `:ractor`
+  message. Extending reliable interruption to the `:ractor`
   concurrency strategy.
 
 ## v12.5.1
@@ -641,7 +812,7 @@ OpenAI, Google, DeepInfra, DeepSeek, and xAI model entries.
 
 * **repl: display command errors in the curses UI** <br>
   Commands invoked with too few arguments now display an error
-  message — `command(<name>): too few arguments` — directly in
+  message: `command(<name>): too few arguments`. Displayed directly in
   the curses transcript area, giving immediate feedback instead
   of silently failing.
 
@@ -765,7 +936,7 @@ a command system foundation with the `/exit` command, and several new
 keybindings (Ctrl+F, Ctrl+K, Ctrl+Y). Tool calls are rendered with a
 compact function-call syntax in the status bar.
 
-Two new built-in tools — `LLM::Tool::Ls` and `LLM::Tool::Which` — are
+Two new built-in tools: `LLM::Tool::Ls` and `LLM::Tool::Which` are
 available as opt-in additions for file listing and executable lookup.
 
 Model metadata has been refreshed across providers, the REPL loop
@@ -832,7 +1003,7 @@ area.
   The curses-based REPL input now detects paste operations by tracking
   the rate at which characters arrive. A paste rate of ≤50ms is
   assumed to be a burst of characters that could only be explained by
-  a paste — no human types that fast. Multiline pastes are supported
+  a paste. No human types that fast. Multiline pastes are supported
   through internal refactoring of the input handling logic.
 
 * **repl: optimize paste mode rendering** <br>
@@ -855,7 +1026,7 @@ area.
 
 * **repl: render tool calls in a function-call syntax** <br>
   The curses-based REPL status bar now renders tool calls with a
-  compact function-call syntax — `tool(key: value)` instead of
+  compact function-call syntax: `tool(key: value)` instead of
   `tool: name`. Strings are quoted and truncated, arrays show their
   first two elements, and hashes collapse to `{…}`, making it easier
   to see what arguments the model is passing. The `tool done` status
@@ -983,8 +1154,8 @@ tracer logger instances with less verbosity.
   streamed content via `#<<`. `LLM::Stream::Disabled` represents an explicitly
   disabled stream with no-op callbacks.
 
-  This is part of an internal refactoring that lets all stream values — IO
-  objects, `true`, `false`, `nil`, and `LLM::Stream` instances themselves —
+  This is part of an internal refactoring that lets all stream values: IO
+  objects, `true`, `false`, `nil`, and `LLM::Stream` instances themselves
   be represented by the same `LLM::Stream` interface via the new
   `LLM::Stream.try` factory method.
 
@@ -1053,7 +1224,7 @@ tracer logger instances with less verbosity.
 
 * **repl: add extra padding between markdown nodes** <br>
   The curses-based REPL markdown renderer now adds extra vertical spacing
-  between certain markdown elements — paragraphs, headers, and codeblocks —
+  between certain markdown elements: paragraphs, headers, and codeblocks
   for improved readability of model responses.
 
 * **repl: add a visual divider between transcript and the rows below it** <br>

data/README.md

@@ -16,9 +16,12 @@ Welcome to the canonical llm.rb repository.
 
 llm.rb is an advanced runtime for building capable AI applications
 on CRuby. By default it has zero runtime dependencies although certain
-functionality – such as ActiveRecord support – require
+functionality (such as ActiveRecord support) require
 optional dependencies that are opt-in.
 
+When you want to learn more than what the README covers, checkout
+the [deepdive.md](https://r.uby.dev/llm/deepdive/).
+
 ## Features
 
 The runtime supports OpenAI, OpenAI-compatible endpoints, Anthropic, Google
@@ -33,12 +36,10 @@ also possible to make a tool call while the model is still streaming.
 
 The runtime builds on top of three core concepts: providers, contexts, and agents,
 so once you learn the fundamentals, everything else falls into place naturally. And once
-you learn llm.rb, you will also be able to use <a href="https://r.uby.dev/mruby-llm">mruby-llm</a> and
+you learn llm.rb, you will also be able to use
+<a href="https://r.uby.dev/mruby-llm">mruby-llm</a> and
 <a href="https://r.uby.dev/wasm-llm">wasm-llm</a> because the API is pretty much identical.
 
-For detailed explanations, configuration, and advanced patterns, see the
-[deepdive.md](https://r.uby.dev/llm/deepdive/).
-
 ## Install
 
 ```bash
@@ -49,7 +50,9 @@ gem install llm.rb
 
 #### LLM::Agent
 
-The [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) class is the default high-level interface,
+The
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
+class is the default high-level interface,
 and it is recommended for most use-cases. It manages tool execution
 automatically, guards against infinite loops, manages conversation
 state, and much more.
@@ -62,13 +65,63 @@ agent = LLM::Agent.new(llm, stream: $stdout)
 agent.talk "Hello world"
 ```
 
+##### set
+
+[`LLM::Agent.set`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#set-class_method)
+is a class-level DSL that accepts a Hash of properties. Each key resolves to a
+corresponding class accessor: `name`, `description`, `model`, `tools`,
+`instructions`, `schema`, `stream`, `tracer`, `concurrency`, `confirm`,
+`path`, and `skills`. All options are optional; zero or more can be set.
+An error is raised for unknown keys so that typos are caught early.
+
+```ruby
+class SystemAdmin < LLM::Agent
+  set name: "sysadmin",
+      description: "system administration agent",
+      model: "deepseek-v4-pro",
+      tools: [Shell]
+end
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = SystemAdmin.new(llm)
+agent.talk "Run 'date'"
+```
+
+##### Persistence
+
+Set `path:` on an agent for automatic filesystem persistence;
+the agent restores conversation history from the file on startup
+and saves it back after every turn, with no manual serialization
+code. For database-backed persistence, ActiveRecord and Sequel
+integrations are also available (see the
+[database deepdive](https://r.uby.dev/llm/deepdive/advanced/database)
+for details). All persistence options use the same underlying
+serialization.
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, path: "session.json")
+agent.talk "remember my name is robert"
+
+# Next time, the conversation is restored automatically:
+agent = LLM::Agent.new(llm, path: "session.json")
+agent.talk "what's my name?"
+```
+
 #### LLM::Context
 
-The [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html) class is at the heart of the runtime
-and it is what [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) uses under the hood.
+The
+[`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
+class is at the heart of the runtime
+and it is what
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
+uses under the hood.
 It requires that the tool call loop be managed manually -
 sometimes that can be useful, but usually for advanced use-cases.
-If you're new to llm.rb, try [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) first.
+If you're new to llm.rb, try
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) first.
 
 ```ruby
 require "llm"
@@ -80,7 +133,9 @@ ctx.talk "Hello world"
 
 #### LLM::Tool
 
-Subclasses of [`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) are plain Ruby classes with
+Subclasses of
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
+are plain Ruby classes with
 an optional set of typed parameters. <br> The model can choose to
 call them on your behalf, and they're one of the most powerful features
 for extending the feature set or abilities of a model.
@@ -101,7 +156,8 @@ end
 #### LLM::Stream
 
 Streams can be simple IO objects or subclasses of
-[`LLM::Stream`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html) with structured callbacks for content,
+[`LLM::Stream`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html)
+with structured callbacks for content,
 reasoning, tool calls, tool returns, and compaction.
 
 ```ruby
@@ -122,16 +178,27 @@ agent.talk "Explain Ruby fibers."
 
 #### LLM::Schema
 
-[`LLM::Schema`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema.html) subclasses produce typed, structured
+[`LLM::Schema`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema.html)
+subclasses produce typed, structured
 output from any model call. Pass a schema to `LLM::Context#talk`,
 `LLM::Agent#talk`, or `LLM::Provider#complete` to receive validated
 JSON instead of free text. Schemas work alongside tools and streams.
 
-[`LLM::Schema`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema.html) can define objects, arrays, enums, nested schemas,
-and more. It is also used internally by [`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) for parameter
+[`LLM::Schema`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema.html)
+can define objects, arrays, enums, nested schemas,
+and more. It is also used internally by
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) for parameter
 definitions, so you already benefit from it when you declare tool
 parameters.
 
+The
+[`LLM::DeepSeek`](https://r.uby.dev/api-docs/llm.rb/LLM/DeepSeek.html)
+provider includes runtime-level optimisations such as structured
+output support (despite no official structured outputs API) and
+SVG image generation. This example uses
+[`LLM::Schema`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema.html) with
+DeepSeek:
+
 ```ruby
 class Weather < LLM::Schema
   property :city, String, "The city name"
@@ -140,7 +207,7 @@ class Weather < LLM::Schema
   required %i[city temperature conditions]
 end
 
-llm = LLM.openai(key: ENV["KEY"])
+llm = LLM.deepseek(key: ENV["KEY"])
 agent = LLM::Agent.new(llm, schema: Weather)
 res = agent.talk "Weather in Paris?"
 res.content!  # => {city: "Paris", temperature: 15.0, conditions: "Cloudy"}
@@ -150,11 +217,11 @@ res.content!  # => {city: "Paris", temperature: 15.0, conditions: "Cloudy"}
 
 The [LLM::Agent#repl](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
 method drops you into a curses-based TUI for talking to an
-agent interactively. The `path:` option saves and restores
-runtime state across sessions. The `tools:` option attaches
+agent interactively. Set `path:` on the agent for automatic
+persistence across REPL sessions. The `tools:` option attaches
 extra tools for the duration of the session. It is like
 `binding.pry` but for agents. For the full reference see the
-[REPL section](https://r.uby.dev/llm/deepdive/#repl) in the
+[REPL section](https://r.uby.dev/llm/deepdive/fundamentals/repl) in the
 deepdive.
 
 ```ruby
@@ -162,17 +229,35 @@ require "llm"
 require "llm/tools"
 
 llm = LLM.deepseek(key: ENV["KEY"])
-agent = LLM::Agent.new(llm, name: "my-agent")
-agent.repl(path: "agent.json", tools: LLM::Tool.subclasses)
+agent = LLM::Agent.new(llm, name: "my-agent", path: "agent.json")
+agent.repl(tools: LLM::Tool.subclasses)
+```
+
+##### CLI
+
+The `llm.rb` executable is available on your PATH after installation.
+It starts a REPL session from any directory:
+
+```bash
+llm.rb                     # auto-detect from $DEEPSEEK_API_KEY
+llm.rb -p openai           # use OpenAI explicitly
+llm.rb -t                  # temporary session, no persistence
 ```
 
+The CLI auto-detects your provider from standard environment variables
+(`DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.).
+Persistent sessions are stored under `~/.llm.rb/` and restored
+automatically on your next visit.
+
 #### LLM::MCP
 
 The Model Context Protocol (MCP) has first-class support
 in llm.rb. The stdio and http transports work out of the
 box. MCP tools are translated into subclasses of
-[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) that can be used with [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
-or [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html).
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) that can be
+used with
+[`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html) or
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html).
 
 ```ruby
 require "llm"
@@ -188,8 +273,10 @@ agent.talk "Run the tool"
 The Agent 2 Agent (A2A) protocol has first-class support
 in llm.rb. The http and jsonrpc transports work out of the
 box. A2A skills are translated into subclasses of
-[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) that can be used with [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
-or [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html).
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) that can be
+used with
+[`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html) or
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html).
 
 ```ruby
 require "llm"
@@ -200,6 +287,38 @@ agent = LLM::Agent.new(llm, stream: $stdout, tools: a2a.skills)
 agent.talk "Run the skill"
 ```
 
+#### LLM::Skill
+
+A skill turns a markdown file into a callable tool. When the model
+calls it, the runtime spawns a subagent with the skill's instructions
+as its system prompt and the skill's own tool set. The subagent runs
+one turn and returns the result, then is discarded. Each call
+is fresh and stateless. For a deeper explanation see the
+[deepdive.md](https://r.uby.dev/llm/deepdive/fundamentals/skills).
+
+**SKILL.md**
+
+```markdown
+---
+name: summary
+description: Reads recent git history and writes a summary
+tools: all
+---
+
+Collect the recent git log, analyze each commit,
+and write a summary to summary.txt.
+```
+
+**agent.rb**
+
+```ruby
+require "llm"
+
+llm   = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm, skills: ["./skills/summary"])
+agent.talk "Summarize the last week of work"
+```
+
 #### RAG
 
 Most providers offer an embedding model that can be
@@ -220,6 +339,8 @@ llm  = LLM.openai(key: ENV["KEY"])
 body = "llm.rb is Ruby's capable AI runtime."
 embedding = llm.embed([body]).embeddings.first
 
+# Document is your ActiveRecord or Sequel model
+# with a vector column (e.g. sqlite-vec or pgvector)
 Document.create!(
   title: "llm.rb",
   body:,
@@ -241,7 +362,7 @@ The `:fork` strategy also provides a separate process that offers
 isolation from its parent.
 
 You can learn more about the llm.rb concurrency model in the
-[deepdive.md](https://r.uby.dev/llm/deepdive/#concurrency).
+[deepdive.md](https://r.uby.dev/llm/deepdive/fundamentals/concurrency).
 
 ```ruby
 require "llm"
@@ -254,7 +375,9 @@ agent.talk "Run the tools in parallel"
 
 #### ORM
 
-Because both [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html), and [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
+Because both
+[`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html) and
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
 can be serialized to JSON and stored in a simple string, both ActiveRecord
 and Sequel support can be implemented within a single column on a single row.
 
@@ -341,9 +464,9 @@ In no particular order:
 <summary>I have a limited budget. What should I do?</summary>
 <br>
 <p>
-There a few options. The first option is to host
+There are a few options. The first option is to host
 your own model, and use the ollama or llamacpp
-providers. This can be diffilcult though because
+providers. This can be difficult though because
 a capable model requires hardware that can
 match it. If you have the ability to self-host,
 this would be my first option.
@@ -368,7 +491,7 @@ If you're on a budget, DeepSeek is hard to beat.
 <details>
 <summary>Can I download llm.rb via a decentralized network?</summary>
 <br>
-You can!
+Yes.
 <br>
 We are on the <a href="https://radicle.network">radicle.network</a>
 <br>
@@ -376,7 +499,9 @@ Every commit that lands on GitHub also lands on Radicle.
 <br>
 Our repository ID is z2PtfQ6dYwyYaW2aGrztG1sMyDmCE.
 <br>
-Browse on <a href="https://radicle.network/nodes/iris.radicle.network/z2PtfQ6dYwyYaW2aGrztG1sMyDmCE">the web</a>.
+Browse on <a
+href="https://radicle.network/nodes/iris.radicle.network/z2PtfQ6dYwyYaW2aGrztG1sMyDmCE">the
+web</a>.
 </details>
 
 ## Resources