Bridgetown2026-08-15T21:42:37-06:00https://maquina.app/feed.xmlComprehensive documentation for Maquina, the open-source Rails framework designed for building modern web applications with a focus on developer experience, performance, and maintainability.Mario Alberto Chávez Cárdenas2026-08-10T00:00:00-06:002026-08-10T00:00:00-06:00repo://posts.collection/_posts/2026-08-10-equipr-cross-agent-skill-manager.md<p>equipr installs skills, commands, and MCP servers from a marketplace or an Agent Plugins source into whichever coding agents are present on a machine: Claude Code, Codex, OpenCode, and Pi. It works through each agent’s own personal config surfaces rather than a plugin system. It is a single Go binary, MIT licensed, and available now via Homebrew or as a standalone install script.</p> <h2 id="the-problem-it-addresses">The problem it addresses</h2> <p>Claude Code has a marketplace mechanism for distributing and updating skills that none of the other three agents come close to matching. Codex, OpenCode, and Pi have no built-in equivalent. The alternatives are copying a skill’s files by hand, which then has to be kept current on its own since nothing does that automatically, or installing an npm package for the skills some maintainers publish that way. The <a href="https://agent-plugins.org/specification">Agent Plugins specification</a> exists to standardize the package format itself, but it does not yet define how any individual agent installs from a source or keeps that installation up to date. That part is still left to each agent’s own tooling, or to something else.</p> <p>The same gap shows up again with isolated per-agent containers, of the kind <a href="/blog/2026/07/introducing-fragua/">Fragua</a> uses: each container needs the same sources installed, and each one is a separate place that update has to reach.</p> <h2 id="what-equipr-resolves">What equipr resolves</h2> <p>equipr treats a source as one of two shapes. A repository with <code class="highlighter-rouge">.claude-plugin/marketplace.json</code> at its root is a marketplace holding one or more plugins. A repository with <code class="highlighter-rouge">plugin.json</code> at its root is a single <a href="https://agent-plugins.org/specification">Agent Plugins</a>-conformant package. Both resolve to the same internal model, addressed the same way:</p> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&lt;source-id&gt;/&lt;plugin&gt;:&lt;component&gt; </code></pre></div></div> <div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gp">$</span><span class="w"> </span>equipr add https://github.com/coreyhaines31/marketingskills <span class="go">Fetching https://github.com/coreyhaines31/marketingskills Added marketingskills (marketplace, fetched via git) with 1 plugin(s) - marketing-skills 2.10.0 </span><span class="gp">$</span><span class="w"> </span>equipr list <span class="go">marketingskills marketplace marketing-skills 2.10.0 49 skills </span><span class="gp">$</span><span class="w"> </span>equipr <span class="nb">install </span>marketingskills/marketing-skills:seo-audit <span class="nt">--yes</span> <span class="go">Installed 1 component(s) into 3 agent(s): </span><span class="gp"> [claude-code] seo-audit (copy -&gt;</span><span class="w"> </span>~/.claude/skills/seo-audit<span class="o">)</span> <span class="gp"> [opencode] seo-audit (symlink -&gt;</span><span class="w"> </span>~/.config/opencode/skills/seo-audit<span class="o">)</span> <span class="gp"> [pi] seo-audit (symlink -&gt;</span><span class="w"> </span>~/.pi/agent/skills/seo-audit<span class="o">)</span> </code></pre></div></div> <p><code class="highlighter-rouge">equipr status</code> reports whether each recorded install still matches its source. <code class="highlighter-rouge">equipr update</code> re-fetches every registered source and re-applies anything that changed. <code class="highlighter-rouge">equipr doctor</code> reports broken symlinks and orphaned records.</p> <h2 id="where-each-agent-differs">Where each agent differs</h2> <p>The four agents agree on very little beyond the skill file format itself. A <code class="highlighter-rouge">SKILL.md</code> is the one point of real convergence across all four. Everywhere else, they differ:</p> <table> <thead> <tr> <th>Agent</th> <th>Skills directory</th> <th>MCP config</th> </tr> </thead> <tbody> <tr> <td>Claude Code</td> <td><code class="highlighter-rouge">~/.claude/skills/</code></td> <td><code class="highlighter-rouge">~/.claude.json</code></td> </tr> <tr> <td>Codex</td> <td><code class="highlighter-rouge">~/.codex/skills/</code></td> <td><code class="highlighter-rouge">~/.codex/config.toml</code></td> </tr> <tr> <td>OpenCode</td> <td><code class="highlighter-rouge">~/.config/opencode/skills/</code></td> <td><code class="highlighter-rouge">~/.config/opencode/opencode.json</code></td> </tr> <tr> <td>Pi</td> <td><code class="highlighter-rouge">~/.pi/agent/skills/</code></td> <td><code class="highlighter-rouge">~/.config/mcp/mcp.json</code></td> </tr> </tbody> </table> <p>Three different config formats, and OpenCode’s MCP schema is not merely a different filename: it requires an explicit <code class="highlighter-rouge">type</code> and a <code class="highlighter-rouge">command</code> array where Claude Code infers both from a single string. equipr’s install step translates a source’s MCP configuration into each target’s native shape rather than writing one format everywhere.</p> <h2 id="installing-into-each-agent">Installing into each agent</h2> <p>equipr places skill and command files where each agent expects them, and merges MCP servers into each agent’s existing config without disturbing anything else already there: no unrelated key is touched, no unrelated setting is reformatted. Installing is the same command regardless of which agent it’s going into; equipr absorbs the difference in how each one stores things.</p> <h2 id="npm-sources-without-an-npm-install">npm sources without an npm install</h2> <p>equipr accepts an npm package as a source. It does not run <code class="highlighter-rouge">npm install</code>. It runs <code class="highlighter-rouge">npm pack</code>, extracts the resulting tarball into its own cache alongside git and archive sources, and reads <code class="highlighter-rouge">plugin.json</code>, <code class="highlighter-rouge">skills/</code>, <code class="highlighter-rouge">commands/</code>, and <code class="highlighter-rouge">mcp.json</code> out of the result. No dependency tree is installed alongside it, and nothing registers as a plugin or a global package in the process.</p> <h2 id="what-equipr-does-not-do">What equipr does not do</h2> <p>equipr never registers itself as a native plugin inside any agent: no entry in Claude Code’s <code class="highlighter-rouge">/plugin</code> list, no npm-global registration, nothing to unregister if the binary is removed. It writes to personal config directories and stops.</p> <h2 id="what-this-reinforced">What this reinforced</h2> <p>Treating each agent’s personal config surface as the integration point, rather than any agent’s own plugin system, is what let one tool support four incompatible agents from a single codebase. The harder requirement turned out to be the opposite of adding capability: writing less to any given file, and writing it more carefully, specifically the single-key-merge discipline for MCP config. That constraint did more to make the tool trustworthy than any feature did.</p> <h2 id="install">Install</h2> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl <span class="nt">-fsSL</span> https://github.com/maquina-app/equipr/releases/latest/download/install.sh | sh </code></pre></div></div> <p>Checksum-verified, installs to <code class="highlighter-rouge">/usr/local/bin</code> when writable, <code class="highlighter-rouge">~/.local/bin</code> otherwise. A Homebrew tap is also available: <code class="highlighter-rouge">brew install maquina-app/tap/equipr</code>.</p> <p>The <a href="/documentation/tools/equipr/">equipr documentation</a> covers every command, every flag, where each file lands per agent, and exit codes for scripting. Source is on <a href="https://github.com/maquina-app/equipr">GitHub</a>, MIT licensed.</p> <p>Maquina’s own Claude Code plugins are distributed as a marketplace equipr can install from: see <a href="/documentation/ai-tools/">AI Tools</a>.</p>Mario Alberto Chávez Cárdenas2026-08-04T00:00:00-06:002026-08-04T00:00:00-06:00repo://posts.collection/_posts/2026-08-04-rails-mcp-server-2-0-0-removing-execute-ruby.md<p>I built the first version of Rails MCP Server before Claude Code, Codex, and tools like them were the popular way to work with AI on a codebase. Back then, Claude Desktop could talk to me and read whatever I pasted into the chat. Nothing else. If I wanted it to see a model’s associations, check a route, or run a quick query against my own data, I copied and pasted. Every question meant leaving the conversation, going to the terminal, and bringing the answer back by hand.</p> <p>That’s the itch Rails MCP Server scratched: let Claude Desktop introspect a Rails project directly (routes, schema, models) without me being the copy-paste layer between every question and its answer. A companion tool, <a href="https://github.com/maquina-app/nvim-mcp-server">nvim-mcp-server</a>, closed the other half of the loop, letting Claude Desktop write code changes straight into my Neovim buffers instead of me pasting a diff and applying it by hand.</p> <p><code class="highlighter-rouge">execute_ruby</code> made sense inside that setup. Claude Desktop had no way to touch my filesystem or run anything on its own. The MCP server was its only hands. Giving it a tool that could run real Ruby inside my running Rails app meant one call could answer what would otherwise take a dozen round trips: an ad-hoc scope, or a quick <code class="highlighter-rouge">Model.find</code> to check a hunch. It was the sharpest tool in the server, and it earned its place.</p> <h2 id="what-changed">What changed</h2> <p>That gap doesn’t exist for most people building with AI anymore. Claude Code, Codex, and the agentic coding tools that followed sit directly on top of the codebase. They already have a shell and the same Ruby your app runs on. If an agent wants to check <code class="highlighter-rouge">User.where(inactive: true).count</code>, it doesn’t need a special MCP tool for that. It can just run it, the way I would from my own terminal.</p> <p>That’s most of the reasoning that justified <code class="highlighter-rouge">execute_ruby</code>, gone. The tool wasn’t wrong when I built it. It answered a real constraint, and that constraint has largely gone away.</p> <h2 id="hardening-a-tool-i-was-already-rethinking">Hardening a tool I was already rethinking</h2> <p>I didn’t arrive here in one step. Yesterday’s 1.6.0 <a href="/blog/2026/08/rails-mcp-server-1-6-0-sandbox-hardening/">release</a> closed several real bypasses in the <code class="highlighter-rouge">execute_ruby</code> sandbox: file reads that slipped past validation and symlinks that walked out of the project, on top of database writes that weren’t actually being rolled back. Today’s 1.6.1 went further: a researcher at Pluto Security responsibly disclosed a command-execution path through <code class="highlighter-rouge">require "pty"</code>, and the fix restricted <code class="highlighter-rouge">require</code> to a small allowlist of data-only libraries, cutting off that path along with a few adjacent ones.</p> <p>Both releases were worth shipping on their own. But writing 1.6.1 is what made the actual problem visible to me: I was patching individual escapes out of a tool whose entire premise is running caller-supplied Ruby with the privileges of the server process. A static scan and some runtime overrides can raise the floor, but they were never going to be a hard boundary. Path validation, transaction rollback, the <code class="highlighter-rouge">confirm_risky</code> gate: every fence I’ve put around <code class="highlighter-rouge">execute_ruby</code> has been best-effort, and 1.6.0 said so plainly. Best-effort is a reasonable trade when a tool is filling a real gap. It stops paying off once that’s no longer true.</p> <h2 id="what-200-does">What 2.0.0 does</h2> <p>Version 2.0.0 removes <code class="highlighter-rouge">execute_ruby</code> outright, rather than hardening it again. The server is introspection-only now, and its dedicated analyzers already cover the ground <code class="highlighter-rouge">execute_ruby</code> was built for:</p> <table> <thead> <tr> <th>Instead of <code class="highlighter-rouge">execute_ruby</code> for…</th> <th>Use</th> </tr> </thead> <tbody> <tr> <td>Reading a file</td> <td><code class="highlighter-rouge">get_file</code></td> </tr> <tr> <td>Finding files</td> <td><code class="highlighter-rouge">list_files</code></td> </tr> <tr> <td>Routes, schema, models, controllers, env, structure</td> <td><code class="highlighter-rouge">get_routes</code>, <code class="highlighter-rouge">get_schema</code>, <code class="highlighter-rouge">analyze_models</code>, <code class="highlighter-rouge">analyze_controller_views</code>, <code class="highlighter-rouge">analyze_environment_config</code>, <code class="highlighter-rouge">project_info</code></td> </tr> </tbody> </table> <p>Ad-hoc data queries (a custom scope, a one-off count) are the one thing this doesn’t replace, on purpose. That was always the part of <code class="highlighter-rouge">execute_ruby</code> doing the most work and carrying the most risk, and it’s exactly the part an agent sitting on top of your code no longer needs a server tool for.</p> <p>Bootstrap tools drop from four to three: <code class="highlighter-rouge">switch_project</code>, <code class="highlighter-rouge">search_tools</code>, <code class="highlighter-rouge">execute_tool</code>. The internal analyzers haven’t changed. They’re still discovered through <code class="highlighter-rouge">search_tools</code> and invoked through <code class="highlighter-rouge">execute_tool</code>, same as before.</p> <p>If you’re on a client without direct code execution and still want <code class="highlighter-rouge">execute_ruby</code>, the 1.6.x line keeps it, now with the 1.6.1 hardening. It isn’t disappearing; it’s just not where the project is headed.</p> <h2 id="upgrading">Upgrading</h2> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gem update rails-mcp-server </code></pre></div></div> <p>If you have <code class="highlighter-rouge">execute_ruby</code> wired into a client’s tool config, remove it from there. Replace file reads with <code class="highlighter-rouge">get_file</code> and globs with <code class="highlighter-rouge">list_files</code>. Everything else keeps working the way it did.</p> <p>For new installations:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gem <span class="nb">install </span>rails-mcp-server rails-mcp-config </code></pre></div></div> <h2 id="where-this-leaves-the-project">Where this leaves the project</h2> <p>A tool that runs arbitrary code is always going to be the most interesting line in a security report, no matter how many layers sit around it. I’d rather ship a Rails MCP Server that doesn’t have that line at all than one that keeps explaining, release after release, why the latest patch finally closes the gap. What’s gone is the one tool whose risk had stopped being worth what it saved me.</p> <p>Thanks again to Pluto Security for the responsible disclosure that shaped both 1.6.1 and this release. If you find a gap, the <a href="https://github.com/maquina-app/rails-mcp-server/issues">issue tracker</a> is open.</p> <h2 id="links">Links</h2> <ul> <li><a href="https://github.com/maquina-app/rails-mcp-server">GitHub Repository</a></li> <li><a href="https://rubygems.org/gems/rails-mcp-server">RubyGems</a></li> <li><a href="https://github.com/maquina-app/rails-mcp-server/releases/tag/v2.0.0">2.0.0 Release Notes</a></li> <li><a href="https://github.com/maquina-app/rails-mcp-server/releases/tag/v1.6.1">1.6.1 Release Notes</a></li> <li><a href="https://github.com/maquina-app/rails-mcp-server/blob/main/SECURITY.md">Security Policy</a></li> </ul>Mario Alberto Chávez Cárdenas2026-08-03T00:00:00-06:002026-08-03T00:00:00-06:00repo://posts.collection/_posts/2026-08-03-rails-mcp-1-6.md<p>The <code class="highlighter-rouge">execute_ruby</code> tool lets an AI model run Ruby in the context of your Rails application. That is genuinely useful. One call can answer a question that would otherwise take a dozen tool round-trips, and it is also the single most dangerous thing this server does. The tool advertises itself as read-only. Version 1.6.0 is about making that promise closer to true.</p> <p>This release started with an uncomfortable review of the sandbox. What I found is that “read-only” had holes you could walk through without trying. So 1.6.0 closes them, adds several layers of defense behind them, and, importantly, is honest about what the sandbox is and isn’t.</p> <h2 id="what-the-sandbox-actually-is">What the sandbox actually is</h2> <p>Worth stating plainly, because it frames everything below: <code class="highlighter-rouge">execute_ruby</code> runs your code through <code class="highlighter-rouge">bin/rails runner</code>. That means real Ruby, with your full application loaded and a live database connection. The sandbox is a combination of static analysis (a scan for dangerous patterns) and runtime overrides of <code class="highlighter-rouge">File</code>, <code class="highlighter-rouge">IO</code>, <code class="highlighter-rouge">Dir</code>, and <code class="highlighter-rouge">Kernel</code>.</p> <p>That is defense-in-depth, not a locked box. It raises the floor; it is not an isolation boundary. Keeping that distinction visible is part of what 1.6.0 fixes. The previous framing implied more safety than the implementation delivered.</p> <h2 id="the-holes-that-were-closed">The holes that were closed</h2> <p><strong>File reads leaked through the siblings.</strong> The sandbox overrode <code class="highlighter-rouge">File.read</code> and <code class="highlighter-rouge">File.open</code>, but not <code class="highlighter-rouge">File.readlines</code>, <code class="highlighter-rouge">File.binread</code>, <code class="highlighter-rouge">File.foreach</code>, or any of the <code class="highlighter-rouge">IO</code> equivalents. Those are separate entry points, and they read arbitrary paths:</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Blocked before 1.6.0:</span> <span class="no">File</span><span class="p">.</span><span class="nf">read</span><span class="p">(</span><span class="s2">"/etc/passwd"</span><span class="p">)</span> <span class="c1"># =&gt; PATH ERROR</span> <span class="c1"># Wide open before 1.6.0:</span> <span class="no">IO</span><span class="p">.</span><span class="nf">read</span><span class="p">(</span><span class="s2">"/etc/passwd"</span><span class="p">)</span> <span class="c1"># read anything</span> <span class="no">File</span><span class="p">.</span><span class="nf">readlines</span><span class="p">(</span><span class="s2">"/etc/passwd"</span><span class="p">)</span> </code></pre></div></div> <p>Every read entry point now routes through the same path validation.</p> <p><strong>Raw readers, still exposed:</strong> the overrides kept the originals around as public aliases like <code class="highlighter-rouge">File.original_read</code>, so user code could just call the un-sandboxed method directly. Those are gone from the public surface now; the native handles live in private constants the sandbox uses internally.</p> <p><strong>Symlinks could point out of the project.</strong> Path validation expanded paths but never resolved symlinks, so a link inside the project that pointed at <code class="highlighter-rouge">/etc/passwd</code> passed the check and then read the target. Validation now resolves the real path first, and the allowlist for system data (the timezone directories Rails needs for <code class="highlighter-rouge">Time.zone</code>) is matched against canonical locations so it keeps working on macOS, where <code class="highlighter-rouge">/usr/share/zoneinfo</code> is itself a symlink.</p> <p><strong>Half-blocked <code class="highlighter-rouge">ENV</code>:</strong> the scan rejected <code class="highlighter-rouge">ENV[...]</code> and <code class="highlighter-rouge">ENV.fetch</code>, but <code class="highlighter-rouge">ENV.to_h</code>, <code class="highlighter-rouge">ENV.values_at</code>, and <code class="highlighter-rouge">ENV.each</code> walked straight past it and handed over every secret in the process environment. The scan now rejects <code class="highlighter-rouge">ENV</code> access broadly, while still leaving <code class="highlighter-rouge">Rails.env</code> alone.</p> <h2 id="the-layers-added-behind-them">The layers added behind them</h2> <p>Closing bypasses is necessary but not sufficient. A blocklist can always be out-metaprogrammed. So 1.6.0 adds controls that don’t depend on catching every trick.</p> <p><strong>Database writes are rolled back.</strong> This is the big one, because “read-only” was never true for data. Nothing stopped <code class="highlighter-rouge">User.delete_all</code> or a raw <code class="highlighter-rouge">DELETE</code>. Now your code runs inside a transaction that is <em>always</em> rolled back:</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># This executes, returns a count, and then is undone:</span> <span class="no">User</span><span class="p">.</span><span class="nf">where</span><span class="p">(</span><span class="ss">inactive: </span><span class="kp">true</span><span class="p">).</span><span class="nf">delete_all</span> <span class="c1"># =&gt; 42 (and the 42 rows are still there)</span> </code></pre></div></div> <p>It is harm reduction, not a guarantee (DDL auto-commits on some adapters like MySQL, and <code class="highlighter-rouge">after_commit</code> callbacks don’t fire), but the common accident is now a no-op instead of data loss.</p> <p><strong>The timeout actually stops the code.</strong> The previous timeout wrapped the subprocess call and, when it fired, stopped <em>waiting</em>, while the runaway <code class="highlighter-rouge">rails runner</code> kept going, orphaned. The command now runs in its own process group, and a timeout kills the whole group. A runaway query or an infinite loop is terminated, not abandoned.</p> <p><strong>Dual-use constructs ask first.</strong> Some things are legitimately useful and also the classic sandbox-escape tools: <code class="highlighter-rouge">send</code>, <code class="highlighter-rouge">public_send</code>, <code class="highlighter-rouge">const_get</code>, <code class="highlighter-rouge">Kernel#open</code>. Rather than silently allowing them or hard-blocking them, the tool now stops and explains:</p> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>CONFIRMATION REQUIRED: This code uses constructs that can bypass the sandbox's static safety checks: - `send`: dynamic dispatch can invoke methods the static scan cannot see, e.g. reaching blocked system/file APIs indirectly. Ask the user to review the code and confirm. If they approve, re-invoke execute_ruby with confirm_risky: true. </code></pre></div></div> <p>The model can’t wave this through on its own. A human reviews the code, and only then does the call run with <code class="highlighter-rouge">confirm_risky: true</code>. It puts a person in the loop exactly where the static analysis runs out of road.</p> <h2 id="being-honest-about-the-boundary">Being honest about the boundary</h2> <p>I want to be direct about the limits, because a security tool that oversells itself is worse than one that doesn’t. These controls are layered defense, not hard isolation. The tool still executes real Ruby with full application access, so a determined bypass is possible; DDL and writes on non-default connections can escape the rollback; there are no per-process CPU or memory caps beyond the timeout.</p> <p>If you need stronger guarantees, the right moves are outside the Ruby layer: run the server against a database user with read-only grants, and/or run it inside an OS-level sandbox (a container, <code class="highlighter-rouge">sandbox-exec</code>, seccomp). The <code class="highlighter-rouge">SECURITY.md</code> in the repository now documents both the controls and these limitations so you can make an informed call.</p> <h2 id="manager-agnostic-ruby-resolution">Manager-agnostic Ruby resolution</h2> <p>Separate from the sandbox, 1.6.0 fixes a long-standing annoyance for anyone whose Ruby isn’t the system default. Tools that shell out to <code class="highlighter-rouge">bin/rails</code> (<code class="highlighter-rouge">execute_ruby</code>, <code class="highlighter-rouge">get_schema</code>, and the introspection halves of <code class="highlighter-rouge">analyze_models</code> and <code class="highlighter-rouge">analyze_controller_views</code>) were exporting the rbenv-only <code class="highlighter-rouge">RBENV_VERSION</code> and running a login shell. On macOS, <code class="highlighter-rouge">path_helper</code> then reshuffled <code class="highlighter-rouge">PATH</code> so <code class="highlighter-rouge">bin/rails</code> booted under system Ruby and failed.</p> <p>The runner now prepends the active version manager’s shims directory to <code class="highlighter-rouge">PATH</code> (mise, asdf, or rbenv, honoring <code class="highlighter-rouge">MISE_DATA_DIR</code>, <code class="highlighter-rouge">XDG_DATA_HOME</code>, <code class="highlighter-rouge">ASDF_DATA_DIR</code>, and <code class="highlighter-rouge">RBENV_ROOT</code>) and uses a non-login shell so the project’s Ruby survives. rvm, which has no shims, is sourced when present. The version comes from your project’s <code class="highlighter-rouge">.ruby-version</code>, <code class="highlighter-rouge">.tool-versions</code>, or <code class="highlighter-rouge">.mise.toml</code>, so different projects can use different Rubies with no extra configuration.</p> <p>While I was in there, the analyzer path stopped swallowing errors with <code class="highlighter-rouge">2&gt;/dev/null</code>, so a Rails boot failure now surfaces the real message instead of a blank “Error executing Rails command.”</p> <h2 id="namespaced-models-resolve-properly">Namespaced models resolve properly</h2> <p><code class="highlighter-rouge">analyze_models</code> could report a module-namespaced model as “not found” depending on how you referred to it. It now resolves from every input form: <code class="highlighter-rouge">Namespace::Model</code>, the path <code class="highlighter-rouge">namespace/model</code>, the flattened <code class="highlighter-rouge">NamespaceModel</code>, and the bare leaf <code class="highlighter-rouge">Model</code>. That holds independent of your app’s custom inflections. The introspection runner also derives the constant from the resolved file instead of interpolating raw input, which removes an injection surface in the generated scripts along the way.</p> <h2 id="breaking-change-ruby-32-is-dropped">Breaking change: Ruby 3.2 is dropped</h2> <p>The minimum supported Ruby is now <strong>3.3</strong> (<code class="highlighter-rouge">required_ruby_version &gt;= 3.3.0</code>), and CI tests 3.3 and 3.4. The dependency updates in this release pull in transitive gems that require 3.3, so this was forced rather than chosen. If you’re on 3.2, upgrade your Ruby before updating the gem.</p> <h2 id="security-and-dependencies">Security and dependencies</h2> <p>The dependency bump is also a security update. Upgrading to Puma 8.0.2 clears CVE-2026-47736 and CVE-2026-47737 (both HIGH, covering PROXY Protocol v1 remote memory exhaustion and repeated-header handling), and the lockfile refresh clears a <code class="highlighter-rouge">concurrent-ruby</code> advisory. <code class="highlighter-rouge">bundler-audit</code> reports clean.</p> <h2 id="upgrading">Upgrading</h2> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gem update rails-mcp-server </code></pre></div></div> <p>Make sure you’re on Ruby 3.3 or newer first. If you use Claude Desktop, restart it to pick up the new version; the binary path in your configuration doesn’t change.</p> <p>For new installations:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gem <span class="nb">install </span>rails-mcp-server rails-mcp-config </code></pre></div></div> <h2 id="whats-next">What’s Next</h2> <p>Giving a model a Ruby runtime inside your app is a sharp tool. This release makes the edges more honest: fewer accidental cuts, and a clear label on what the guard does and doesn’t cover. The durable next step is real isolation: read-only database roles and OS-level sandboxing as first-class, documented setups rather than footnotes.</p> <p>If you find a gap, the <a href="https://github.com/maquina-app/rails-mcp-server/issues">issue tracker</a> is open, and security reports have a private channel through the repository’s <a href="https://github.com/maquina-app/rails-mcp-server/security">Security tab</a>. Pull requests are welcome.</p> <h2 id="links">Links</h2> <ul> <li><a href="https://github.com/maquina-app/rails-mcp-server">GitHub Repository</a></li> <li><a href="https://rubygems.org/gems/rails-mcp-server">RubyGems</a></li> <li><a href="/documentation/ai-tools/rails-mcp-server/">Documentation</a></li> <li><a href="https://github.com/maquina-app/rails-mcp-server/blob/main/SECURITY.md">Security Policy</a></li> <li><a href="https://github.com/maquina-app/rails-mcp-server/blob/main/docs/AGENT.md">AI Agent Guide</a></li> </ul>Mario Alberto Chávez Cárdenas2026-07-27T00:00:00-06:002026-07-27T00:00:00-06:00repo://posts.collection/_posts/2026-07-27-maquina-components-0-6-0-themeable-beyond-color.md<p>Maquina Components, the server-rendered UI component library for Rails and Tailwind, is out in 0.6.0. It adds a token layer for radius, elevation, focus rings and font weight, moves all engine CSS into <code class="highlighter-rouge">@layer components</code>, and fixes a focus ring that had been dead on six of seven button variants. The release is deliberately breaking: seven changes, and the first one fails silently in every existing application.</p> <p>Until now the library was themeable in color and in nothing else. Radius, elevation, focus rings, font weight and hover states were written directly into the stylesheets, so changing any of them meant overriding selectors rather than declaring values. Theming one real application against <a href="https://maquina.app/blog/2026/07/maquina-components-0-5-0-drawer-and-scaffold-templates/">the 0.5 releases</a> took roughly 1,700 lines of override CSS, and most of that was not expressing a design. It was reaching past the cascade.</p> <h2 id="why-tokens-alone-would-not-have-fixed-it">Why tokens alone would not have fixed it</h2> <p>Every engine rule was unlayered and carried specificity from its variant and state qualifiers, so appearance and structure shared one flat cascade. A theme could not reach the appearance without also being able to break the structure, and the engine defended against that by being hard to override at all. Adding tokens on top of that arrangement would have changed nothing.</p> <p>Three things changed together. There is now a token layer: <code class="highlighter-rouge">--control-radius</code>, <code class="highlighter-rouge">--surface-radius</code>, <code class="highlighter-rouge">--focus-ring-width</code>, <code class="highlighter-rouge">--elevation-raised</code>, <code class="highlighter-rouge">--label-weight</code> and the rest, declared in <code class="highlighter-rouge">@theme</code> and read from every rule that used to hardcode a value. All twenty stylesheets moved into <code class="highlighter-rouge">@layer components</code>, which is what lets a caller’s Tailwind utilities apply. And specificity is flat now: every rule sits at 0,1,0, with variants and states in <code class="highlighter-rouge">:where()</code>, so a theme’s <code class="highlighter-rouge">[data-component="button"]</code> means every button, which it previously did not.</p> <p>Which gives a contract worth stating plainly: a theme changes values, not selectors. Reach for a selector only when you want to change a component’s shape, like a different padding rhythm or a variant the engine does not ship.</p> <p>A flat theme is six lines:</p> <div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nd">:root</span> <span class="p">{</span> <span class="py">--elevation-control</span><span class="p">:</span> <span class="nb">none</span><span class="p">;</span> <span class="py">--elevation-raised</span><span class="p">:</span> <span class="nb">none</span><span class="p">;</span> <span class="py">--elevation-overlay</span><span class="p">:</span> <span class="nb">none</span><span class="p">;</span> <span class="py">--control-radius</span><span class="p">:</span> <span class="m">0.25rem</span><span class="p">;</span> <span class="py">--surface-radius</span><span class="p">:</span> <span class="m">0.25rem</span><span class="p">;</span> <span class="p">}</span> </code></pre></div></div> <p>The <a href="https://maquina.app/documentation/components/theming/">theming guide</a> has the full token reference. Every component demo on the documentation site now carries a <strong>shape</strong> toggle in its chrome; flip it to <code class="highlighter-rouge">brutal</code> or <code class="highlighter-rouge">soft</code> and the whole library changes shape from token declarations alone.</p> <h2 id="the-focus-ring-was-dead">The focus ring was dead</h2> <p><code class="highlighter-rouge">[data-component="button"]:focus-visible</code> was declared before the variant rules, at the same specificity. Each variant then re-declared <code class="highlighter-rouge">box-shadow</code> for its own elevation, and later-at-equal-specificity wins. The focus ring was silently overwritten on every variant that set a shadow.</p> <p>On the demo page, two of the sixteen buttons showed a ring, and both were <code class="highlighter-rouge">destructive</code> — the only variant that happened to re-declare its own focus rule after its variant rule. Primary, secondary, outline, ghost and link had no visible keyboard focus at all. That is a WCAG 2.4.7 failure. It shipped, and it was invisible in code review because every rule involved looked correct on its own.</p> <p>Focus is now an <code class="highlighter-rouge">outline</code> rather than a <code class="highlighter-rouge">box-shadow</code>. Outlines do not participate in <code class="highlighter-rouge">box-shadow</code>, so a variant’s elevation can no longer overwrite a ring. They survive forced-colors mode, and they are not clipped by <code class="highlighter-rouge">overflow: hidden</code> ancestors, which had been quietly cutting rings off inside the sidebar and drawer. Every focusable button rings now, and a test asserts that state rules follow variant rules in every stylesheet, so the ordering that caused this cannot come back.</p> <h2 id="your-utility-classes-now-win">Your utility classes now win</h2> <p><code class="highlighter-rouge">css_classes:</code> is the documented way to adjust one instance of a component, and it has been partly a lie. Because engine rules were unlayered, they beat any Tailwind utility passed through them:</p> <ul> <li><code class="highlighter-rouge">[data-component="input"]</code> set <code class="highlighter-rouge">w-full</code>, so any <code class="highlighter-rouge">w-*</code> you passed was dead.</li> <li><code class="highlighter-rouge">[data-form-part="actions"]</code> set <code class="highlighter-rouge">display: flex</code>, so <code class="highlighter-rouge">sm:hidden</code> did nothing.</li> <li><code class="highlighter-rouge">[data-component="form"]</code> set <code class="highlighter-rouge">display: grid</code>. Pass <code class="highlighter-rouge">sm:flex-row</code> and it silently stopped being a row.</li> </ul> <p>These are layout failures, not restyles, and they failed quietly, which is why the workaround was always a wrapper element. With the engine in <code class="highlighter-rouge">@layer components</code>, utilities win. Measured: an input with a width utility goes from 448px to 137px.</p> <p>Worth searching your views for <code class="highlighter-rouge">css_classes:</code> after upgrading. Anything you passed as decoration and never saw is about to take effect.</p> <h2 id="before-you-upgrade-run-the-scanner">Before you upgrade: run the scanner</h2> <p>The release ships a scanner. Run it inside your application:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bin/rails maquina:doctor </code></pre></div></div> <p>It reads your CSS, views and JavaScript and prints <code class="highlighter-rouge">file:line</code> for every pattern this release changes, grouped by severity: the unlayered <code class="highlighter-rouge">*</code> rule, component overrides the token layer makes redundant, restated SVG data URIs, <code class="highlighter-rouge">[data-active]</code> presence selectors, <code class="highlighter-rouge">.dark</code> twins. It never edits anything and always exits 0.</p> <h2 id="breaking-changes">Breaking changes</h2> <p>Seven. The first affects every existing application and fails silently.</p> <ol> <li> <p><strong>The preflight shim in your <code class="highlighter-rouge">theme.css</code> now outranks the engine.</strong> Your installed <code class="highlighter-rouge">theme.css</code> carries this rule:</p> <div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">*</span> <span class="p">{</span> <span class="nl">border-color</span><span class="p">:</span> <span class="nf">var</span><span class="p">(</span><span class="l">--color-border</span><span class="p">);</span> <span class="p">}</span> </code></pre></div> </div> <p>Unlayered CSS outranks every layer at any specificity. Now that engine rules live in <code class="highlighter-rouge">@layer components</code>, that one universal rule wins over the tinted borders on all alert and toast variants: a destructive alert renders with a plain grey border where 0.5.1 painted a red one. The generator template is fixed, but the rule lives in your file. Wrap it:</p> <div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">@layer</span> <span class="n">base</span> <span class="p">{</span> <span class="o">*</span> <span class="p">{</span> <span class="nl">border-color</span><span class="p">:</span> <span class="nf">var</span><span class="p">(</span><span class="l">--color-border</span><span class="p">);</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div> </div> </li> <li><strong>Utility classes now win.</strong> Anything passed through <code class="highlighter-rouge">css_classes:</code> that was previously overridden by an engine rule will take effect.</li> <li><strong>Radius and elevation defaults normalize.</strong> Card goes 12px to 8px, popovers 6px to 8px, and four <code class="highlighter-rouge">shadow-lg</code> sites collapse to <code class="highlighter-rouge">--elevation-overlay</code>.</li> <li><strong>Focus rings become outlines</strong>, and form fields stop ringing on mouse click.</li> <li><strong><code class="highlighter-rouge">merge_component_data</code> precedence narrows</strong> to identity keys.</li> <li><strong>Surfaces that sit above the page stop painting <code class="highlighter-rouge">--background</code>.</strong></li> <li><strong>Tinted badges lose a stray hairline</strong> the shim had been forcing onto them.</li> </ol> <p>Every one of them is a value, so the <a href="https://maquina.app/documentation/components/upgrading/">upgrading guide</a> closes with an appendix that restores the 0.5.1 look with a single token block.</p> <h2 id="upgrading">Upgrading</h2> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bundle update maquina-components </code></pre></div></div> <p>Then re-run the installer to append the new shape and state tokens to your theme. It is idempotent and will not touch your palette:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bin/rails generate maquina_components:install </code></pre></div></div> <p>Then read the <a href="https://maquina.app/documentation/components/upgrading/">upgrading guide</a>.</p> <h2 id="also-in-this-release">Also in this release</h2> <p>New:</p> <ul> <li>Drawer gained <code class="highlighter-rouge">title</code>, <code class="highlighter-rouge">description</code>, <code class="highlighter-rouge">section</code> and <code class="highlighter-rouge">separator</code> partials. The first two had been styled by CSS since the beginning with nothing to emit them, so the documentation told you to hand-write <code class="highlighter-rouge">&lt;h2 class="text-lg font-semibold"&gt;</code>.</li> <li>Sidebar gained menu badges, menu actions and group actions on the same footing.</li> <li>There is a <code class="highlighter-rouge">label</code> partial now, which makes the required-field indicator reachable.</li> </ul> <p>Fixed:</p> <ul> <li><code class="highlighter-rouge">dropdown_menu_simple</code> raised <code class="highlighter-rouge">NoMethodError</code> and <code class="highlighter-rouge">combobox_simple</code> rendered an empty popover. Both had zero call sites in the repository, which is exactly why they shipped broken.</li> <li>Two components were building correct data attributes and then discarding them, so <code class="highlighter-rouge">[data-variant="bordered"]</code> on a table was unreachable.</li> </ul> <h2 id="what-this-reinforced">What this reinforced</h2> <p>Every bug in this release looked correct in the stylesheet. The focus ring rule was right there in the file, and the dead table variant was right there in the partial. What caught them was asserting on compiled output and computed styles: does this token reach the browser, does this rule come after that one, does this element actually have a ring. The tests that came out of the audit assert those things.</p> <p>The quieter finding was a set of styled hooks that turned out to be emitted by nothing at all — CSS that read as supported API and matched no markup. That is worse than a missing feature, because it looks finished. Six became real partials here and two were deleted.</p> <h2 id="documentation">Documentation</h2> <ul> <li><a href="https://maquina.app/documentation/components/theming/">Theming</a></li> <li><a href="https://maquina.app/documentation/components/upgrading/">Upgrading</a></li> <li><a href="https://maquina.app/documentation/components/">Component documentation</a></li> </ul> <h2 id="source">Source</h2> <ul> <li><a href="https://github.com/maquina-app/maquina_components">Maquina Components</a></li> <li><a href="https://github.com/maquina-app/maquina_components/compare/v0.5.1...v0.6.0">Full Changelog</a></li> <li><a href="https://rubygems.org/gems/maquina-components/versions/0.6.0">Gem on RubyGems</a></li> </ul>Mario Alberto Chávez Cárdenas2026-07-20T00:00:00-06:002026-07-20T00:00:00-06:00repo://posts.collection/_posts/2026-07-20-introducing-nexo.md<p>Ruby has most of the pieces you need to build an AI agent already, and they’re good. <code class="highlighter-rouge">ruby_llm</code> gives you a provider-neutral chat loop and tool calling that’s cleaner than most language SDKs out there, one API across a dozen providers instead of a new SDK per vendor. <code class="highlighter-rouge">ruby_llm-skills</code> gives you SKILL.md loading. <code class="highlighter-rouge">ruby_llm-mcp</code> gives you MCP servers. <code class="highlighter-rouge">ruby_llm-schema</code> gives you structured output. What none of them give you is a front door, one place where those pieces snap together with defaults you don’t have to think about twice.</p> <p>Building an agent on top of these gems means wiring the same sandbox and permissions boilerplate into every new project, by hand, every time. Nexo exists to stop that. It doesn’t rebuild the tool-call loop, skill loading, MCP, or structured output; those already exist, they’re well built, and duplicating them would just make Nexo worse at the things <code class="highlighter-rouge">ruby_llm</code> and its ecosystem already do well. Nexo sits on top of them instead. Two things were missing from the ecosystem, and those are the two things Nexo adds: a sandbox and permissions seam, and a real job primitive called <code class="highlighter-rouge">WorkflowRun</code>.</p> <h2 id="agent--model--harness">Agent = Model + Harness</h2> <p>A model on its own forgets everything the moment it finishes a response. Turning “a model that replies” into “an agent that does work” takes tools, a place for those tools to act, a policy for what they’re allowed to do, and a way to track a job from start to finish. That collection of things is the harness. Ruby has all of it, but scattered across gems with different DSLs, and wiring them by hand is the first thing every new agent project reinvents.</p> <p>Nexo is the nexus: the connective tissue between a model and everything else an agent needs, and between the fragmented RubyLLM-ecosystem gems and one coherent whole.</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">require</span> <span class="s2">"nexo"</span> <span class="k">class</span> <span class="nc">CodeReviewer</span> <span class="o">&lt;</span> <span class="no">Nexo</span><span class="o">::</span><span class="no">Agent</span> <span class="n">model</span> <span class="no">ENV</span><span class="p">.</span><span class="nf">fetch</span><span class="p">(</span><span class="s2">"NEXO_MODEL"</span><span class="p">)</span> <span class="c1"># any ruby_llm model, no vendor default</span> <span class="n">sandbox</span> <span class="ss">:local</span> <span class="n">permissions</span> <span class="ss">:read_only</span> <span class="n">instructions</span> <span class="s2">"You are a careful code reviewer. Read files and report issues. Do not write files."</span> <span class="k">end</span> <span class="no">CodeReviewer</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="ss">cwd: </span><span class="s2">"/path/to/repo"</span><span class="p">).</span><span class="nf">prompt</span><span class="p">(</span><span class="s2">"Review the auth module"</span><span class="p">)</span> </code></pre></div></div> <h2 id="what-nexo-adds-a-sandbox-and-permissions-seam">What Nexo adds: a sandbox and permissions seam</h2> <p>An agent’s tools have to act <em>somewhere</em>, and something has to decide what they’re allowed to do there. Nexo splits that into two questions, where (the sandbox) and what (the permission mode), and answers both safely by default: <code class="highlighter-rouge">:virtual</code> sandbox, <code class="highlighter-rouge">:read_only</code> permissions. An untrusted model gets zero host access until you opt into more, explicitly, in your own code.</p> <ul> <li><strong><code class="highlighter-rouge">Virtual</code></strong> runs in memory with zero host access. <code class="highlighter-rouge">#shell</code> raises <code class="highlighter-rouge">NotImplementedError</code> on purpose, that’s the safety property, not a bug in waiting.</li> <li><strong><code class="highlighter-rouge">Local</code></strong> gives you the host filesystem and shell for trusted dev and CI work. Every path is guarded to stay inside <code class="highlighter-rouge">cwd</code>, and the shell only sees <code class="highlighter-rouge">PATH</code>, <code class="highlighter-rouge">HOME</code>, and <code class="highlighter-rouge">LANG</code>. It never sees your full environment.</li> <li><strong><code class="highlighter-rouge">Container</code></strong> runs tools inside a throwaway Docker or Apple <code class="highlighter-rouge">container</code> sandbox, hardened by default (no network, dropped capabilities, read-only rootfs), with every hardening an explicit opt-out. Full flag reference is in the <a href="/documentation/nexo/sandboxes/#container-sandbox--docker--apple-container">sandboxes doc</a>.</li> <li><strong><code class="highlighter-rouge">Remote</code></strong> is a four-method contract, <code class="highlighter-rouge">read</code>, <code class="highlighter-rouge">write</code>, <code class="highlighter-rouge">exec</code>, <code class="highlighter-rouge">close</code>, that you adapt to whatever provider you’re already using. Nexo ships zero vendor code here; swap the injected object and you’ve swapped providers.</li> </ul> <p>A write under <code class="highlighter-rouge">:read_only</code>, a shell call on <code class="highlighter-rouge">Virtual</code>, any denied action comes back as <code class="highlighter-rouge">{ error: ... }</code> and the loop keeps running. The model can read that and adjust; a permission denial isn’t a reason to crash the process. A path that tries to escape its sandbox is a different kind of failure, and it raises <code class="highlighter-rouge">SecurityError</code> instead.</p> <h2 id="what-nexo-adds-workflowrun">What Nexo adds: WorkflowRun</h2> <p>An agent accumulates context, it’s a conversation that keeps going. A lot of real work isn’t that. It’s a finite task that starts, does something, and finishes with a result you can check on later, sometimes from a different process entirely. Nothing in the ecosystem covered that cleanly, so Nexo adds <code class="highlighter-rouge">Workflow</code>.</p> <p>A workflow can drive an agent too, so the two primitives Nexo owns fold into one recipe: stage inputs into the run’s sandbox, run the agent against them, capture the output. The <code class="highlighter-rouge">agent</code> class macro names the agent, and <code class="highlighter-rouge">run_agent</code> runs it bound to the run’s own sandbox:</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">class</span> <span class="nc">Summarizer</span> <span class="o">&lt;</span> <span class="no">Nexo</span><span class="o">::</span><span class="no">Agent</span> <span class="n">model</span> <span class="no">ENV</span><span class="p">.</span><span class="nf">fetch</span><span class="p">(</span><span class="s2">"NEXO_MODEL"</span><span class="p">)</span> <span class="c1"># any ruby_llm model, no vendor default</span> <span class="n">instructions</span> <span class="s2">"Summarize the given text in two plain sentences. No commentary."</span> <span class="k">end</span> <span class="k">class</span> <span class="nc">SummarizeDocument</span> <span class="o">&lt;</span> <span class="no">Nexo</span><span class="o">::</span><span class="no">Workflow</span> <span class="n">agent</span> <span class="no">Summarizer</span> <span class="k">def</span> <span class="nf">call</span><span class="p">(</span><span class="n">payload</span><span class="p">)</span> <span class="n">emit</span><span class="p">(</span><span class="ss">:started</span><span class="p">,</span> <span class="ss">doc_id: </span><span class="n">payload</span><span class="p">[</span><span class="ss">:doc_id</span><span class="p">])</span> <span class="n">response</span> <span class="o">=</span> <span class="n">run_agent</span><span class="p">(</span><span class="s2">"Summarize this document:</span><span class="se">\n\n</span><span class="si">#{</span><span class="n">payload</span><span class="p">[</span><span class="ss">:text</span><span class="p">]</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span> <span class="n">emit</span><span class="p">(</span><span class="ss">:summarized</span><span class="p">,</span> <span class="ss">length: </span><span class="n">response</span><span class="p">.</span><span class="nf">content</span><span class="p">.</span><span class="nf">length</span><span class="p">)</span> <span class="p">{</span> <span class="ss">summary: </span><span class="n">response</span><span class="p">.</span><span class="nf">content</span> <span class="p">}</span> <span class="k">end</span> <span class="k">end</span> <span class="n">run</span> <span class="o">=</span> <span class="no">SummarizeDocument</span><span class="p">.</span><span class="nf">run</span><span class="p">(</span><span class="ss">doc_id: </span><span class="mi">123</span><span class="p">,</span> <span class="ss">text: </span><span class="s2">"Long text..."</span><span class="p">)</span> <span class="n">run</span><span class="p">.</span><span class="nf">id</span> <span class="c1"># =&gt; "0191d6b2-..." (UUID v7, time-ordered)</span> <span class="n">run</span><span class="p">.</span><span class="nf">status</span> <span class="c1"># =&gt; "done"</span> <span class="n">run</span><span class="p">.</span><span class="nf">result</span> <span class="c1"># =&gt; { "summary" =&gt; "The document covers ..." }</span> </code></pre></div></div> <p>Every run gets a stable id, a status, a payload, a result, and an ordered event log you can replay with <code class="highlighter-rouge">Nexo::Workflow.logs(run.id)</code> or <code class="highlighter-rouge">rake nexo:logs[id]</code>. The agent’s tool calls and its final response land in that same log alongside the workflow’s own <code class="highlighter-rouge">:started</code>/<code class="highlighter-rouge">:summarized</code> events, so a driven run reads as one story instead of two logs stitched together by hand. Outside Rails it all records to memory and just works offline, no database required; inside Rails, install the migration and the same code persists to a <code class="highlighter-rouge">nexo_workflow_runs</code> table instead, with no other change.</p> <p>A workflow that raises is recorded as <code class="highlighter-rouge">failed</code> and the exception still propagates to your caller, the opposite of a tool failure, which returns <code class="highlighter-rouge">{ error: ... }</code> and never interrupts the agent loop. Jobs that need to pause and pick back up later, waiting on a human approval or a slow external process, get the same lifecycle extended with checkpoints, <code class="highlighter-rouge">suspend!</code>, and <code class="highlighter-rouge">resume</code>, covered in the <a href="/documentation/nexo/durable-workflows/">durable workflows doc</a>.</p> <h2 id="provider-neutral-on-purpose">Provider-neutral, on purpose</h2> <p>The only hard dependency is <code class="highlighter-rouge">ruby_llm</code>. No hardcoded default model, no vendor SDK called directly anywhere in the core loop; every example in the docs pulls the model from <code class="highlighter-rouge">ENV.fetch("NEXO_MODEL")</code>, just as happy pointing at a local Ollama model as a hosted one. <code class="highlighter-rouge">ruby_llm-skills</code>, <code class="highlighter-rouge">ruby_llm-mcp</code>, and an optional Anthropic-oriented autonomous loop are all soft dependencies, required lazily, and they raise a clear <code class="highlighter-rouge">Nexo::MissingDependencyError</code> with install instructions if you haven’t added them. You only pay for what you use.</p> <h2 id="where-it-stands-today">Where it stands today</h2> <p>Nexo is early and the API isn’t stable yet. The <a href="/documentation/nexo/sandboxes/#container-sandbox--docker--apple-container">Apple <code class="highlighter-rouge">container</code> runtime parity table</a> in the docs says so plainly: Docker is the verified path today, and Apple’s CLI flags are encoded from the reference mapping but not yet confirmed against a live daemon. The caveat is published rather than papered over.</p> <p>What’s shipped: the sandbox and permissions seam across <code class="highlighter-rouge">Virtual</code>, <code class="highlighter-rouge">Local</code>, <code class="highlighter-rouge">Container</code>, and <code class="highlighter-rouge">Remote</code>; the <code class="highlighter-rouge">Workflow</code>/<code class="highlighter-rouge">WorkflowRun</code> lifecycle with staging, artifacts, and durable checkpoints; skills, MCP behind a fail-closed gate, a web fetch tool with an SSRF guard, sessions, and a Rails engine with generators for the conventional <code class="highlighter-rouge">app/agents</code> / <code class="highlighter-rouge">app/workflows</code> / <code class="highlighter-rouge">app/skills</code> layout.</p> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gem "nexo_ai" </code></pre></div></div> <p>The gem publishes as <code class="highlighter-rouge">nexo_ai</code>; everything in the code lives under <code class="highlighter-rouge">Nexo::</code>.</p> <p>None of this exists without the RubyLLM ecosystem underneath it. Nexo was worth building because that foundation, <a href="https://github.com/crmne/ruby_llm"><code class="highlighter-rouge">ruby_llm</code></a> and everything built around it, is solid.</p> <p>The <a href="/documentation/nexo/">Nexo documentation</a> has the full index, sandboxes, permissions, tools, loop backends, workflows, durable workflows, skills, MCP, web, sessions, Rails, and concurrency. If you’re already building on <code class="highlighter-rouge">ruby_llm</code> and you’ve written this same sandbox-and-permissions setup more than once, this is for you.</p> <p>Repo: <a href="https://github.com/maquina-app/nexo">github.com/maquina-app/nexo</a></p>Mario Alberto Chávez Cárdenas2026-07-12T00:00:00-06:002026-07-12T00:00:00-06:00repo://posts.collection/_posts/2026-07-12-maquina-components-0-5-0-drawer-and-scaffold-templates.md<p>This release adds a Turbo-aware Drawer component, a <code class="highlighter-rouge">scaffold_templates</code> generator that makes <code class="highlighter-rouge">rails generate scaffold</code> produce styled views, and engine helpers included in the generated helper module. It’s also a first for the project: most of it came from contributors.</p> <h2 id="drawer">Drawer</h2> <p>A slide-out panel with an overlay backdrop, built from sub-partials the same way Card and Sidebar are. A <code class="highlighter-rouge">provider</code> owns the state; <code class="highlighter-rouge">header</code>, <code class="highlighter-rouge">content</code>, and <code class="highlighter-rouge">footer</code> structure the panel; a <code class="highlighter-rouge">trigger</code> toggles it and a <code class="highlighter-rouge">close</code> dismisses it.</p> <div class="language-erb highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;%=</span> <span class="n">render</span> <span class="s2">"components/drawer/provider"</span><span class="p">,</span> <span class="ss">default_open: </span><span class="n">drawer_open?</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%=</span> <span class="n">render</span> <span class="s2">"components/drawer"</span><span class="p">,</span> <span class="ss">state: </span><span class="n">drawer_state</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%=</span> <span class="n">render</span> <span class="s2">"components/drawer/header"</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="nt">&lt;h2</span> <span class="na">class=</span><span class="s">"text-lg font-semibold"</span><span class="nt">&gt;</span>Filters<span class="nt">&lt;/h2&gt;</span> <span class="cp">&lt;%=</span> <span class="n">render</span> <span class="s2">"components/drawer/close"</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="k">end</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%=</span> <span class="n">render</span> <span class="s2">"components/drawer/content"</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="c">&lt;!-- Panel body --&gt;</span> <span class="cp">&lt;%</span> <span class="k">end</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%=</span> <span class="n">render</span> <span class="s2">"components/drawer/footer"</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="c">&lt;!-- Apply / Reset --&gt;</span> <span class="cp">&lt;%</span> <span class="k">end</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="k">end</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="k">end</span> <span class="cp">%&gt;</span> </code></pre></div></div> <p>Drop a <code class="highlighter-rouge">trigger</code> anywhere on the page as a plain toggle button:</p> <div class="language-erb highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;%=</span> <span class="n">render</span> <span class="s2">"components/drawer/trigger"</span> <span class="cp">%&gt;</span> </code></pre></div></div> <p>The drawer opens from the right by default; pass <code class="highlighter-rouge">side: :left</code> to open from the other edge.</p> <p><strong>Features:</strong> compound structure (<code class="highlighter-rouge">provider</code>, <code class="highlighter-rouge">header</code>, <code class="highlighter-rouge">content</code>, <code class="highlighter-rouge">footer</code>, <code class="highlighter-rouge">trigger</code>, <code class="highlighter-rouge">close</code>), left or right side with an overlay backdrop, a configurable <code class="highlighter-rouge">Cmd/Ctrl+D</code> shortcut, cookie-based state persistence, and full Turbo Drive and Morph compatibility.</p> <h3 id="surviving-turbo">Surviving Turbo</h3> <p>The reason a drawer is more than a CSS transition is the lifecycle around it. The controller handles the three places Turbo usually breaks a stateful component:</p> <p><strong>Cache teardown.</strong> Before Turbo snapshots the page for its cache, the drawer closes and hides its backdrop. A restored snapshot never comes back frozen mid-transition.</p> <p><strong>Morph awareness.</strong> With <code class="highlighter-rouge">turbo_refresh_method_tag :morph</code>, the server re-renders the page in its default state—it doesn’t know the drawer was open. The controller re-reads its cookie on morph and reasserts the correct state—the same fix <a href="https://maquina.app/blog/2026/02/maquina-components-0-4-0-turbo-compatibility/">the sidebar got in 0.4.0</a>.</p> <p><strong>Persistence.</strong> State lives in a cookie, so the drawer holds across full page loads and Turbo navigations alike.</p> <p>That state is exposed through three helpers, so your server-rendered markup and the client agree on the first paint:</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">drawer_state</span> <span class="c1"># =&gt; :open or :closed</span> <span class="n">drawer_open?</span> <span class="c1"># =&gt; true / false</span> <span class="n">drawer_closed?</span> <span class="c1"># =&gt; true / false</span> </code></pre></div></div> <p>Passing <code class="highlighter-rouge">default_open: drawer_open?</code> into the provider and <code class="highlighter-rouge">state: drawer_state</code> into the drawer, as in the usage above, is what closes the loop between the cookie and the initial render.</p> <h2 id="scaffold-templates">Scaffold Templates</h2> <p>Having a component library is one thing; getting your generated code to use it is another. The new <code class="highlighter-rouge">scaffold_templates</code> generator closes that gap.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bin/rails generate maquina_components:scaffold_templates </code></pre></div></div> <p>It copies a set of ERB scaffold templates—<code class="highlighter-rouge">index</code>, <code class="highlighter-rouge">show</code>, <code class="highlighter-rouge">new</code>, <code class="highlighter-rouge">edit</code>, <code class="highlighter-rouge">_form</code>, and the record partial—into <code class="highlighter-rouge">lib/templates/erb/scaffold/</code>. Rails has always let you override its generator templates from that path; what was missing was a set that renders with the component library. Now they ship with the gem.</p> <p>From then on, the standard scaffold generator produces styled views out of the box:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bin/rails generate scaffold Post title:string body:text </code></pre></div></div> <p>You get tables, buttons, and form fields built with Maquina Components instead of Rails’ default markup—before writing any view code. Because the templates are copied into your app, they’re yours to edit afterward.</p> <h2 id="engine-helpers-in-the-generated-module">Engine Helpers in the Generated Module</h2> <p>A quieter change in the same direction. The generated <code class="highlighter-rouge">MaquinaComponentsHelper</code> now includes <code class="highlighter-rouge">IconsHelper</code>, <code class="highlighter-rouge">SidebarHelper</code>, and <code class="highlighter-rouge">ToastHelper</code>. Helpers like <code class="highlighter-rouge">icon_for</code>, <code class="highlighter-rouge">sidebar_open?</code>, and <code class="highlighter-rouge">toast_flash_messages</code> are available in host-app views without an extra <code class="highlighter-rouge">include</code> in <code class="highlighter-rouge">ApplicationHelper</code>. It’s a one-line diff in the template that removes a papercut every new install used to hit—reaching for <code class="highlighter-rouge">icon_for</code> and getting a <code class="highlighter-rouge">NoMethodError</code> because the module wasn’t wired up yet.</p> <h2 id="icon-class-handling">Icon Class Handling</h2> <p>The one bug fix this release tightens <code class="highlighter-rouge">apply_icon_options</code>. It now guards against <code class="highlighter-rouge">nil</code> and non-string class values, HTML-escapes the class before it reaches the markup, and injects a <code class="highlighter-rouge">class</code> attribute onto <code class="highlighter-rouge">&lt;svg&gt;</code> elements that didn’t already have one. Small, but exactly the kind of edge case that only surfaces once icons are being passed around inside real templates.</p> <h2 id="contributors">Contributors</h2> <p>This release was built mostly by two people who aren’t me:</p> <ul> <li><a href="https://github.com/GregorioNeto">@GregorioNeto</a> — the Drawer component (#21) and the icon class handling fix (#17)</li> <li><a href="https://github.com/JuanVqz">@JuanVqz</a> — the <code class="highlighter-rouge">scaffold_templates</code> generator (#20) and the engine helper modules in the generated helper (#19)</li> </ul> <p>Thank you both.</p> <h2 id="upgrading">Upgrading</h2> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bundle update maquina_components </code></pre></div></div> <p>Then, when you want styled scaffolds, install the templates:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bin/rails generate maquina_components:scaffold_templates </code></pre></div></div> <p>There are no breaking changes in this release.</p> <h2 id="what-this-reinforced">What This Reinforced</h2> <p>Three of the four changes pull the same way: they make the gem lean on Rails instead of sitting next to it. The scaffold templates go through Rails’ own generator override path. Helpers are included the way any Rails helper is. And the Drawer keeps its state in a cookie and reacts to Turbo’s morph, the way the sidebar already does. Less to learn, fewer seams to trip over.</p> <p>The other thing worth saying is that I reviewed this release more than I wrote it. Gregorio and Juan built the components; I merged them. That says more about where the project is than any one feature does.</p> <h2 id="documentation">Documentation</h2> <ul> <li><a href="https://maquina.app/documentation/components/drawer/">Drawer</a></li> <li><a href="https://maquina.app/documentation/components/">Component documentation</a></li> </ul> <h2 id="source">Source</h2> <ul> <li><a href="https://github.com/maquina-app/maquina_components">Maquina Components</a></li> <li><a href="https://github.com/maquina-app/maquina_components/compare/v0.4.4...v0.5.0">Full Changelog</a></li> <li><a href="https://rubygems.org/gems/maquina-components/versions/0.5.0">Gem on RubyGems</a></li> </ul>Mario Alberto Chávez Cárdenas2026-07-06T00:00:00-06:002026-07-06T00:00:00-06:00repo://posts.collection/_posts/2026-07-06-introducing-fragua.md<p><a href="https://fragua.app">Fragua</a> is live in private beta. It’s an AI agent orchestrator built specifically for Rails developers, and it’s the newest product under the <a href="https://maquina.app">Maquina</a> umbrella.</p> <p>Fragua is Spanish for <em>forge</em> — the place where raw material becomes a finished tool under heat and pressure. That’s the intent: take a project from a one-line idea to a shipped pull request, running through research, planning, spec-driven development, and execution.</p> <h2 id="why-we-built-it">Why we built it</h2> <p>Coding agents are good at writing code and bad at remembering why. Every new session tends to start from zero — the spec gets re-pasted, the data model gets re-explained, and the agent has no memory of a decision it helped make yesterday.</p> <p>What Fragua actually sells isn’t an AI that writes code. It’s <strong>durable context and a disciplined workflow</strong>. Each phase — brief, research, plan, spec — produces a structured artifact that persists in the workspace and becomes context for the next agent. By the time the execution agent runs, it’s not guessing; it’s reading the plan, the technical guide, and the spec that already exist.</p> <h2 id="the-shape-of-it">The shape of it</h2> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Foundation → Spec → Execution → Pull Request </code></pre></div></div> <p>Only Foundation (a working copy of your codebase) and an accepted Spec are required. Everything else — Product Brief, Research, MVP Plan, Brand Guide, Technical Guide — is optional enrichment that makes the execution agent sharper without ever gating it. Execution itself starts on its own: a sweep every ~2 minutes picks up accepted specs and approved issue fixes, so there’s no button for “start the build.”</p> <p>Under the hood, Fragua splits the work across two planes — a web app that plans and directs, and your own machine that actually runs the agent and pushes the branch. We walk through that split, plus a live tour of the web app, in the video below.</p> <h2 id="rails-first-not-rails-only">Rails-first, not Rails-only</h2> <p>Every new app Fragua scaffolds is Rails 8.1 with Hotwire — Stimulus controllers, Minitest fixtures, Turbo Streams, the full set of conventions the agents already know how to read and write. That part is deliberate and non-negotiable: it’s what lets Fragua write code that looks like it belongs in your app instead of generic output.</p> <p>Where you’re pointing Fragua at a codebase that already exists, the door is wider. Foundation and the Spec and Issue agents read your repo rather than dictate its stack, so brownfield projects outside Rails are something we’re genuinely open to exploring — if that’s your situation, say so in your access request and tell us what you’re working in.</p> <h2 id="whats-actually-different-day-to-day">What’s actually different day to day</h2> <ul> <li><strong>Durable context</strong> — nothing evaporates between sessions; later phases build on everything earlier ones produced.</li> <li><strong>BYOK</strong> — tokens bill straight to your own Anthropic account. Fragua never proxies the call, never stores the key, can’t see your bill.</li> <li><strong><a href="https://fragua.app/observability">Full observability</a></strong> — a live run timeline, per-turn cost broken down by phase and rolled up by workspace and month, and a durable audit trail. Metering, not gating — there are no spend caps to trip.</li> <li><strong>Institutional memory</strong> — the Knowledge Base, every phase artifact, and the full run history live in the workspace, not in one person’s head. When someone hands off or leaves, the context stays.</li> <li><strong>Your host, your code</strong> — agents run on your machine, against your repo, with your own git and GitHub credentials. Nothing you own leaves it.</li> <li><strong>Claude Code today, Codex coming</strong> — the agent runtime is Claude Code right now, with Codex support coming shortly.</li> <li><strong>Sandboxed if you want it</strong> — run the agent directly on your host, or isolate it inside Docker or a macOS Container instead. Setup is in the CLI guide.</li> </ul> <h2 id="watch-the-two-plane-split-in-action">Watch the two-plane split in action</h2> <script type="application/ld+json"> { "@context": "https://schema.org", "@type": "VideoObject", "name": "What is Fragua?", "description": "A live tour of Fragua's two-plane architecture — the web app that plans and directs, and the agent that runs on your machine and pushes the branch.", "thumbnailUrl": "https://maquina.app/images/og-fragua-announcement.jpeg", "uploadDate": "2026-07-06", "embedUrl": "https://player.vimeo.com/video/1206870407", "publisher": { "@type": "Organization", "name": "Maquina", "logo": { "@type": "ImageObject", "url": "https://maquina.app/images/maquina_logo_horizontal.svg" } } } </script> <div class="not-prose my-8 overflow-hidden rounded-2xl"> <div style="padding:56.25% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/1206870407?h=4181fb6856&amp;title=0&amp;byline=0&amp;portrait=0&amp;badge=0&amp;autopause=0&amp;player_id=0&amp;app_id=58479" frameborder="0" allow="autoplay; fullscreen; picture-in-picture; clipboard-write; encrypted-media; web-share" referrerpolicy="strict-origin-when-cross-origin" style="position:absolute;top:0;left:0;width:100%;height:100%;" title="What is Fragua?" loading="lazy"></iframe></div><script src="https://player.vimeo.com/api/player.js"></script> </div> <hr /> <h2 id="where-things-stand">Where things stand</h2> <p>Fragua is in <strong>private beta</strong>, by invitation. A human reads every request before a seat opens — there’s no schedule, seats open based on fit rather than a calendar.</p> <table> <thead> <tr> <th>Plan</th> <th>Price</th> <th>Includes</th> </tr> </thead> <tbody> <tr> <td>Solo</td> <td>$19/month</td> <td>1 user, unlimited workspaces, full cost dashboard, per-feature worktrees, BYOK</td> </tr> <tr> <td>Team</td> <td>$69/month, flat</td> <td>2–10 users, <a href="https://fragua.app/teams">shared workspaces</a>, admin &amp; member roles, audit trail across every run, priority support, BYOK</td> </tr> <tr> <td>Enterprise</td> <td>Contact for quote</td> <td>11+ users, unlimited workspaces, on-premises deployment, dedicated support, BYOK</td> </tr> </tbody> </table> <p>All plans are <strong>free for the duration of the beta</strong>. Pricing begins 30 days after public launch, with email notice ahead of time. A read-only viewer role is on the roadmap — not shipped yet.</p> <p><strong>Need more than 10 seats, or want it on-premises?</strong> Email <a href="mailto:mario@fragua.app">mario@fragua.app</a> and we’ll work out the details directly.</p> <p>If you’re building on Rails 8.x and Hotwire — solo, freelance, a small consultancy, or a growing product team — request access at <a href="https://fragua.app/#access">fragua.app/#access</a>. Working in something else on an existing codebase? Tell us in the request; we’d like to hear about it.</p> <p>The full docs live at <a href="https://fragua.app">fragua.app</a>, including dedicated pages on <a href="https://fragua.app/observability">observability</a>, <a href="https://fragua.app/teams">teams</a>, and <a href="https://fragua.app/trust">trust</a>.</p> <p>Agents that respect the craft. Your host, your keys, your repo.</p> <hr /> <p><em>Fragua is built by <a href="https://maquina.app/">Maquina</a>.</em></p>Mario Alberto Chávez Cárdenas2026-06-11T00:00:00-06:002026-06-11T00:00:00-06:00repo://posts.collection/_posts/2026-06-11-recuerd0-mcp-and-redesign.md<p><a href="https://recuerd0.ai/">recuerd0</a> has always had multiple ways to access your knowledge: a <a href="https://recuerd0.ai/api-docs">REST API</a>, a <a href="https://recuerd0.ai/cli">CLI</a> for terminal workflows, and an <a href="https://recuerd0.ai/agents">agents guide</a> for hooking coding agents directly into your memories. The access model has been there from the start — Bearer token, call the endpoints, get your context back.</p> <p>MCP adds another path. Instead of configuring the connection upfront, any MCP client can reach your memories on demand — mid-conversation, mid-task, whenever the context is needed — without a token to copy or a config file to edit. Building that properly meant adding an OAuth 2.1 authorization server, a consent screen, and connected application management — surface area that needed to feel right in the browser.</p> <p>While that work was underway, the editing experience got the same attention. The textarea that had always been good enough stopped feeling good enough when you’re managing a knowledge base you actually rely on. The fix was already sitting in plain sight: 37signals shipped House MD with Writebook, and it fit recuerd0’s requirements almost exactly.</p> <p>Both changes landed at the same time, alongside a UI pass that tightened the information hierarchy across the workspace and memory views.</p> <hr /> <h2 id="mcp-support">MCP support</h2> <p>recuerd0 runs a remote MCP server at <code class="highlighter-rouge">POST /mcp</code> — Streamable HTTP, JSON-RPC 2.0, compatible with any client that speaks the protocol.</p> <p>The connection is consent-based. The client registers itself with Dynamic Client Registration, you approve a short permission screen in the browser, and that’s it. No token to generate, no config to edit. Approve once per client; disconnect any time from your profile.</p> <p><img src="/images/recuerd0-mcp/mcp.png" alt="recuerd0 OAuth consent screen approving an MCP client connection, with connected application management in the browser" /></p> <p>The authorization server is built directly into the Rails app — no external OAuth service, no added dependencies. PKCE instead of shared secrets. Access tokens last one hour; refresh tokens rotate silently, so a connected client stays connected without interrupting you.</p> <h3 id="six-tools">Six tools</h3> <p>The server exposes six tools across three read and three write operations, all scoped to your account’s workspaces:</p> <table> <thead> <tr> <th>Tool</th> <th>Type</th> <th>What it does</th> </tr> </thead> <tbody> <tr> <td><code class="highlighter-rouge">list_workspaces</code></td> <td>read</td> <td>List the workspaces in your account</td> </tr> <tr> <td><code class="highlighter-rouge">list_memories</code></td> <td>read</td> <td>List memories; optional FTS5 <code class="highlighter-rouge">query</code> and <code class="highlighter-rouge">category</code> filter</td> </tr> <tr> <td><code class="highlighter-rouge">read_memory</code></td> <td>read</td> <td>Read the full content of one memory</td> </tr> <tr> <td><code class="highlighter-rouge">create_memory</code></td> <td>write</td> <td>Create a memory, with optional tags</td> </tr> <tr> <td><code class="highlighter-rouge">update_memory</code></td> <td>write</td> <td>Update title, content, category, or tags</td> </tr> <tr> <td><code class="highlighter-rouge">create_version</code></td> <td>write</td> <td>Append an immutable version, preserving history</td> </tr> </tbody> </table> <p>Read tools require the <code class="highlighter-rouge">memories:read</code> scope. Write tools — including <code class="highlighter-rouge">create_version</code> — require <code class="highlighter-rouge">memories:write</code>. Scopes map to the existing <code class="highlighter-rouge">read_only</code> / <code class="highlighter-rouge">full_access</code> permission tiers, so there’s no parallel auth system to reason about.</p> <p><code class="highlighter-rouge">create_version</code> is the one worth pausing on. Every memory in recuerd0 already has a versioning model — you can snapshot a decision or convention as it evolves and keep the full history. The MCP tool exposes that directly. If a client updates a memory and you want to preserve what was there before, it can append a version rather than overwrite.</p> <h3 id="connect-it">Connect it</h3> <p>The MCP endpoint is at your instance URL:</p> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>https://recuerd0.ai/mcp </code></pre></div></div> <p>For self-hosted instances, replace the domain with your own. Any MCP client that supports custom connectors — Claude Desktop, Claude.ai, Cursor, and others — can connect by pointing at that URL. The OAuth handshake runs itself.</p> <p>Full documentation is at <a href="https://recuerd0.ai/mcp">recuerd0.ai/mcp</a>.</p> <hr /> <h2 id="the-editor">The editor</h2> <p>recuerd0 stores knowledge as markdown. The editing experience should match that — not fight it. A plain textarea works, but it asks you to hold the syntax in your head while you write. After using it long enough, the friction starts to matter.</p> <p><img src="/images/recuerd0-mcp/editor.png" alt="recuerd0's new markdown editor based on House MD, with a minimal toolbar for bold, italic, quote, code, link, and lists" /></p> <p>The new editor is based on <a href="https://once.com/writebook">House MD</a> — the markdown editor 37signals built for Writebook. Minimal toolbar: bold, italic, quote, code, link, bullet list, numbered list. It writes markdown, not HTML. No mode switching, no preview tab — what you see while editing stays close to what the rendered output looks like.</p> <p>One thing worth being explicit about: everything that reads your memories — the API, the CLI, MCP tools — still gets raw markdown. The editor doesn’t change that contract.</p> <hr /> <h2 id="the-ui">The UI</h2> <p>recuerd0 is built on <a href="https://maquina.app/documentation/components/">Maquina Components</a> — a Rails component library with cards, badges, buttons, dialogs, and form elements. The component foundation was already there; this pass refined how those pieces are composed and extended them with patterns specific to what recuerd0 actually is.</p> <p><img src="/images/recuerd0-mcp/better-ui.png" alt="Redesigned recuerd0 workspace view with a deliberate information hierarchy, a labeled pinned section, and list/grid view preferences" /></p> <p>The workspace and memory views got a more deliberate information hierarchy — metadata where you need it, actions reachable on touch and keyboard, pinned items in their own labeled section rather than blended into the list. The color system was tightened so the app reads consistently across every page, and view preferences (list vs grid, cards vs compact) now persist between sessions.</p> <p>The workspace index and workspace show pages have been updated. Memory show, the editor page, and settings are next.</p> <hr /> <p>The MCP server is live. Full documentation at <a href="https://recuerd0.ai/mcp">recuerd0.ai/mcp</a>.</p> <p>recuerd0 is free to self-host. Managed hosting is $15/month.</p> <h2 id="related-reading">Related reading</h2> <ul> <li><a href="/blog/2026/04/recuerd0-api-release/">Recuerd0 Now Reads Like a Filesystem</a> — grep, glob, and ranged read on your memories.</li> <li><a href="/blog/2026/02/announcing-recuerd0/">Announcing Recuerd0</a> — the original launch and the problem we set out to solve.</li> <li><a href="/blog/2026/02/recuerd0-source-code-now-available/">Recuerd0 source code is now available</a> — how to self-host under OSAASY.</li> </ul>Mario Alberto Chávez Cárdenas2026-04-07T00:00:00-06:002026-04-07T00:00:00-06:00repo://posts.collection/_posts/2026-04-07-recuerd0-api-release.md<p><em>The new Recuerd0 API release teaches the memory store to behave like a filesystem — so AI agents already fluent in <code class="highlighter-rouge">grep</code>, <code class="highlighter-rouge">glob</code>, and <code class="highlighter-rouge">read</code> need no new vocabulary.</em></p> <hr /> <p><a href="https://recuerd0.ai/">Recuerd0</a> is the persistent memory store for AI coding agents built by Maquina, and this release reshapes how agents read from it. When an AI agent reaches into Recuerd0 for context, the bottleneck has never been storage. It has been <em>how much</em> the agent has to pull back to get to the one fact it needs. A 2,000-line transcript should not have to fit within the agent’s context window to answer “did we decide to use Postgres?” The new release fixes that — and a handful of other long-standing rough edges — by giving the API the same primitives every coding agent already knows: <code class="highlighter-rouge">glob</code>, <code class="highlighter-rouge">grep</code>, and ranged <code class="highlighter-rouge">read</code>.</p> <p>Here is what is new.</p> <h2 id="file-tool-api-glob-grep-and-ranged-read-on-memories">File-tool API: glob, grep, and ranged read on memories</h2> <p>The biggest shift in this release is conceptual. Memories are no longer monolithic blobs that you fetch whole. They are addressable like files.</p> <p><strong>Glob.</strong> The browse and list endpoints accept a <code class="highlighter-rouge">title</code> glob pattern. <code class="highlighter-rouge">*</code> matches any sequence of characters, <code class="highlighter-rouge">?</code> matches a single character. Combined with <code class="highlighter-rouge">tags</code>, <code class="highlighter-rouge">source</code>, <code class="highlighter-rouge">category</code>, and <code class="highlighter-rouge">workspace_id</code>, the agent can narrow a thousand memories down to the dozen worth looking at without reading any bodies.</p> <div class="language-http highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err">GET /memories.json?title=Meeting*&amp;tags=design,api&amp;category=decision </span></code></pre></div></div> <p><strong>Ranged read.</strong> <code class="highlighter-rouge">GET /workspaces/:id/memories/:id.json</code> now accepts <code class="highlighter-rouge">line_start</code> and <code class="highlighter-rouge">line_end</code> (1-based, inclusive). The response always echoes <code class="highlighter-rouge">total_lines</code>, so the client knows how much memory is available and can compute a tail window in a single follow-up call.</p> <div class="language-http highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err">GET /workspaces/1/memories/42.json?line_start=40&amp;line_end=55 </span></code></pre></div></div> <p>There is no <code class="highlighter-rouge">head=</code> or <code class="highlighter-rouge">tail=</code> parameter — and that is deliberate. <code class="highlighter-rouge">line_start=1&amp;line_end=20</code> is “head 20”; <code class="highlighter-rouge">line_start=(total_lines - 19)&amp;line_end=total_lines</code> is “tail 20”. One verb covers both, and the client never has to learn a parallel vocabulary for the same operation.</p> <p><strong>Grep with line numbers.</strong> <code class="highlighter-rouge">?mode=grep&amp;q=&lt;query&gt;</code> switches the same endpoint into a grep response. Instead of returning the body, it returns an array of matches:</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> </span><span class="nl">"content"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"total_lines"</span><span class="p">:</span><span class="w"> </span><span class="mi">2174</span><span class="p">,</span><span class="w"> </span><span class="nl">"matches"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"line_number"</span><span class="p">:</span><span class="w"> </span><span class="mi">1247</span><span class="p">,</span><span class="w"> </span><span class="nl">"line"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Decided: Postgres for the analytics warehouse, SQLite for everything else."</span><span class="p">,</span><span class="w"> </span><span class="nl">"context_before"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"## Database choice"</span><span class="p">],</span><span class="w"> </span><span class="nl">"context_after"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Reason: ops simplicity outweighs the JOIN ceiling for our scale."</span><span class="p">]</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre></div></div> <p>Optional <code class="highlighter-rouge">context</code>, <code class="highlighter-rouge">before</code>, and <code class="highlighter-rouge">after</code> parameters control how many surrounding lines to return — capped at 10 each, like <code class="highlighter-rouge">grep -C</code>, <code class="highlighter-rouge">-B</code>, and <code class="highlighter-rouge">-A</code>. The full-text search endpoint (<code class="highlighter-rouge">/search.json</code>) supports the same grep mode for cross-memory queries.</p> <p>The <strong>two-step recipe</strong> the agent should reach for: first, use grep to locate the line numbers; then issue a follow-up <code class="highlighter-rouge">line_start</code>/<code class="highlighter-rouge">line_end</code> call to fetch only the surrounding window. A 2,000-line memory becomes a 20-line answer.</p> <h2 id="memory-categories">Memory categories</h2> <p>Every memory now carries a category: <code class="highlighter-rouge">decision</code>, <code class="highlighter-rouge">discovery</code>, <code class="highlighter-rouge">preference</code>, or <code class="highlighter-rouge">general</code> (the default). It is a small thing, but it changes how an agent reasons about what it is reading. A <code class="highlighter-rouge">decision</code> is load-bearing — something the team chose and is sticking with. A <code class="highlighter-rouge">discovery</code> is a fact about the world. A <code class="highlighter-rouge">preference</code> is taste. The agent does not have to infer the difference from prose; it is right there in the metadata, filterable from any list endpoint.</p> <div class="language-http highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err">GET /memories.json?category=decision&amp;sort=updated_at </span></code></pre></div></div> <h2 id="cross-workspace-memory-links">Cross-workspace memory links</h2> <p>Memories can now reference each other across workspaces with first-class “see also” links. The Rails decision in your <em>Backend</em> workspace can point to the deployment write-up in <em>Infrastructure</em> without copying anything. Each memory’s response includes a <code class="highlighter-rouge">links_count</code> so the agent knows there is more context one hop away, and dedicated endpoints under <code class="highlighter-rouge">/memories/:id/links</code> let it list and traverse them.</p> <p>This is the connective tissue for context that lives in more than one place — which, in practice, is most context worth keeping.</p> <h2 id="workspace-wake-up-endpoint">Workspace wake-up endpoint</h2> <p>A new endpoint, <code class="highlighter-rouge">GET /workspaces/:id/context.json</code>, returns a compact “wake-up” payload for an agent starting a fresh session: workspace metadata, recent memory titles, and the highlights an agent should know about before it does anything else. It is the answer to “you are picking up where you left off, here is the room you just walked into.”</p> <p>Pair it with a Claude Code session-start hook and a new conversation begins with the right context already loaded — no manual <code class="highlighter-rouge">recuerd0 memory list</code> dance, no asking the user to repeat themselves.</p> <h2 id="http-caching-across-the-api">HTTP caching across the API</h2> <p>All read endpoints now emit <code class="highlighter-rouge">ETag</code> and <code class="highlighter-rouge">Last-Modified</code> headers and respect conditional requests. A client that sends <code class="highlighter-rouge">If-None-Match</code> for a memory it already has receives a <code class="highlighter-rouge">304 Not Modified</code> response with an empty body. For agents that re-fetch the same workspace several times in a session, this is a meaningful drop in tokens shipped over the wire — and a meaningful drop in load on the database.</p> <p>Grep and ranged-read responses are correctly bypassed by the cache, since they are derived from query parameters that change with each call.</p> <h2 id="cli-recuerd0-memory-read">CLI: <code class="highlighter-rouge">recuerd0 memory read</code></h2> <p>The <a href="https://github.com/maquina-app/recuerd0-cli">recuerd0-cli</a> gains a <code class="highlighter-rouge">memory read</code> command group that wraps the new endpoints so a human (or a terminal-bound agent) can use them without hand-crafting URLs:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>recuerd0 memory <span class="nb">read head </span>42 <span class="nt">--lines</span> 20 recuerd0 memory <span class="nb">read tail </span>42 <span class="nt">--lines</span> 20 recuerd0 memory <span class="nb">read </span>lines 42 <span class="nt">--start</span> 100 <span class="nt">--end</span> 140 recuerd0 memory <span class="nb">read grep </span>42 <span class="s2">"Postgres"</span> <span class="nt">--context</span> 2 <span class="nt">--pretty</span> </code></pre></div></div> <p>In <code class="highlighter-rouge">--pretty</code> mode, the grep subcommand emits a breadcrumb for each hit, suggesting the exact <code class="highlighter-rouge">memory read lines</code>, followed by a call to fetch a window around it. The two-step pattern is right there in the output — no thinking required.</p> <h2 id="agent-guidance-baked-in">Agent guidance baked in</h2> <p>The Claude Code <a href="https://github.com/maquina-app/rails-claude-code">recuerd0 agent skill</a> now ships guidance for <em>when</em> to use the new primitives, not just how. The dedup-before-write protocol prefers <code class="highlighter-rouge">memory read grep</code> over <code class="highlighter-rouge">memory show</code> for large candidates. The workflow guidelines tell the agent: when <code class="highlighter-rouge">total_lines &gt; ~200</code>, grep first and fetch a window — reserve full reads for memories you genuinely need in their entirety.</p> <p>The point of teaching these patterns to the agent is the same as the point of adding them to the API in the first place: make the cheap thing the obvious thing.</p> <h2 id="documentation">Documentation</h2> <p>Every endpoint above is documented in the public <a href="https://recuerd0.ai/api-docs">API reference</a>, and the <a href="https://recuerd0.ai/cli">CLI reference</a> on recuerd0.ai has been updated to match. The grep→fetch-window workflow is called out as a recipe in both places, with worked examples.</p> <h2 id="why-this-release-matters">Why this release matters</h2> <p>Coding agents are getting fluent. They already know how to use <code class="highlighter-rouge">glob</code>, <code class="highlighter-rouge">grep</code>, and <code class="highlighter-rouge">read</code> — those primitives are how they navigate filesystems every day. Recuerd0’s job is not to invent a new vocabulary for context retrieval; it is to look enough like a filesystem that agents do not have to learn one.</p> <p>This release is that bet, made concrete. A memory is now something you can grep. A workspace is now something you can wake up in. A long transcript no longer has to fit entirely within a context window just so the agent can quote one line from it.</p> <h2 id="get-the-update">Get the update</h2> <ul> <li><strong>SaaS users on <a href="https://recuerd0.ai/">recuerd0.ai</a>:</strong> the new endpoints are live now. No action needed.</li> <li><strong>Self-hosters:</strong> pull the latest <a href="https://github.com/maquina-app/recuerd0">recuerd0</a> image (or <code class="highlighter-rouge">git pull</code> and redeploy with Kamal). Run migrations to pick up the new <code class="highlighter-rouge">category</code> column and the <code class="highlighter-rouge">memory_links</code> table.</li> <li><strong>CLI users:</strong> you must update to the latest version to get the new <code class="highlighter-rouge">memory read</code> commands — <code class="highlighter-rouge">brew upgrade recuerd0-cli</code> (or grab the latest binary from <a href="https://github.com/maquina-app/recuerd0-cli/releases">recuerd0-cli releases</a>). Older CLI versions will not expose the new functionality.</li> <li><strong>Claude Code users:</strong> update the <strong>recuerd0 plugin</strong> from the Claude Code marketplace to pick up the new agent guidance and command reference. Without the plugin update, the agent will keep using the old <code class="highlighter-rouge">memory show</code> flow instead of the new grep-first patterns.</li> </ul> <h2 id="frequently-asked-questions">Frequently asked questions</h2> <p><strong>How do I grep a Recuerd0 memory?</strong> Send <code class="highlighter-rouge">GET /workspaces/:id/memories/:id.json?mode=grep&amp;q=&lt;query&gt;</code>. The response returns line numbers and surrounding context instead of the full body. From the CLI: <code class="highlighter-rouge">recuerd0 memory read grep &lt;id&gt; "&lt;query&gt;" --context 2</code>.</p> <p><strong>What is the difference between ranged read and grep mode?</strong> Grep mode finds <em>where</em> a string appears (returns matching line numbers with context). Ranged read fetches <em>what</em> is at known line numbers via <code class="highlighter-rouge">line_start</code> and <code class="highlighter-rouge">line_end</code>. The recommended workflow is grep first to locate, then ranged read to fetch a window.</p> <p><strong>Do I have to update the CLI and Claude Code plugin?</strong> Yes. The new <code class="highlighter-rouge">memory read</code> commands ship in the latest <a href="https://github.com/maquina-app/recuerd0-cli">recuerd0-cli</a>, and the grep-first agent guidance ships in the updated recuerd0 plugin in the Claude Code marketplace. Older versions will keep working but won’t expose the new endpoints.</p> <p><strong>What are memory categories used for?</strong> Each memory is tagged as <code class="highlighter-rouge">decision</code>, <code class="highlighter-rouge">discovery</code>, <code class="highlighter-rouge">preference</code>, or <code class="highlighter-rouge">general</code>. Agents (and humans) can filter by category to find load-bearing decisions without sifting through general notes.</p> <p><strong>Does HTTP caching apply to grep queries?</strong> No. ETag/Last-Modified caching applies to whole-memory and list reads. Grep and ranged-read responses are derived from query parameters and bypass the cache by design.</p> <h2 id="related-reading">Related reading</h2> <ul> <li><a href="/blog/2026/02/announcing-recuerd0/">Announcing Recuerd0</a> — the original launch and the problem we set out to solve.</li> <li><a href="/blog/2026/02/recuerd0-source-code-now-available/">Recuerd0 source code is now available</a> — how to self-host under OSASSY.</li> <li><a href="/">Maquina open-source projects</a> — the rest of the Rails and AI tooling we maintain.</li> </ul> <hr /> <p><em>Recuerd0 is built by <a href="https://maquina.app/">Maquina</a>. Source available under <a href="https://osaasy.dev/">OSASSY license</a>.</em></p>Mario Alberto Chávez Cárdenas2026-03-23T00:00:00-06:002026-03-23T00:00:00-06:00repo://posts.collection/_posts/2026-03-23-mvp-creator-from-idea-to-documents.md<p>Before writing a single line of code, I need to understand what I’m building. Not abstractly — concretely: who the users are, what the real problem is, what the app is called, what voice it has, what technical decisions I’m making from the start. For a long time, that work happened informally — in scattered notes, in my head, or spread across different roles on a team: product knowledge in one conversation, brand direction in another, architecture in some document nobody kept updated. Now I formalize it with an agent called MVP Creator.</p> <p>In this video — the first in a series about my personal process with AI — I show how I use MVP Creator to generate the complete set of foundation documents for a new project: research report, business plan, brand guide, and technical guide. All of it with three prompts, from an initial idea to documentation ready to hand off to Claude Code.</p> <script type="application/ld+json"> { "@context": "https://schema.org", "@type": "VideoObject", "name": "MVP Creator: From Idea to Documents in Three Prompts", "description": "Full walkthrough of the MVP Creator Claude Code plugin. From an initial app idea to research report, business plan, brand guide, and technical guide in three prompts.", "thumbnailUrl": "https://maquina.app/images/og-blog-mvp-creator.jpg", "uploadDate": "2026-03-23", "embedUrl": "https://player.vimeo.com/video/1175986278", "duration": "PT40M", "publisher": { "@type": "Organization", "name": "Maquina", "logo": { "@type": "ImageObject", "url": "https://maquina.app/images/logo.png" } } } </script> <div class="not-prose my-8 overflow-hidden rounded-2xl"> <div style="padding:56.25% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/1175986278?badge=0&amp;autopause=0&amp;player_id=0&amp;app_id=58479" frameborder="0" allow="autoplay; fullscreen; picture-in-picture; clipboard-write; encrypted-media; web-share" referrerpolicy="strict-origin-when-cross-origin" style="position:absolute;top:0;left:0;width:100%;height:100%;" title="MVP Creator: From Idea to Documents in Three Prompts" loading="lazy"></iframe></div><script src="https://player.vimeo.com/api/player.js"></script> </div> <h2 id="the-three-prompts">The Three Prompts</h2> <p>The example in the video is a photo delivery platform for professional photographers. These are the exact prompts I use, in order.</p> <hr /> <h3 id="prompt-1--the-idea-and-context">Prompt 1 — The Idea and Context</h3> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Help me create an MVP for a photo delivery platform for professional photographers. Think of it as a private gallery where photographers deliver finished work to clients. The core concept: a photographer creates a Project (for a client or personal work), organizes photos into Collections within that project, and shares the gallery via single-use expirable links. Invited clients can view, comment, like, and download photos in their preferred quality. Key features: - Projects with collections and high-resolution photo uploads - Active Storage for thumbnail + quality variants (low/medium/high) - Reorderable photos within collections, cover photo per collection - Shareable links: single-use, expire in 7 days, create read-only sessions - Download: single photo or multi-select as zip, with quality choice Target users: freelance and studio photographers in Latin America Language: Spanish-first, English secondary App name: I'm thinking "Liminal" — open to suggestions Research these competitors: https://www.pic-time.com and https://www.picdrop.com/web — also look at how Google Drive handles shared folder UX as a reference point. Use the MVP Creator skill to generate the full documentation set. </code></pre></div></div> <p>With this prompt the agent launches competitor research, runs through the discovery questions, and generates the four foundation documents: research report, business plan, brand guide, and technical guide.</p> <hr /> <h3 id="prompt-2--brand-voice">Prompt 2 — Brand Voice</h3> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Based on everything we've defined about Liminal — the LATAM market, photographers delivering work to clients, the quiet confidence of the name itself — write a brand voice document. The voice should feel like a photographer who has found their style and doesn't need to announce it. Not austere, but economical. Someone who chooses words the way they choose light — deliberately, with care for what gets left out as much as what stays in. Professionalism here means craft, not corporate. The app handles something personal — a photographer's finished work, a client's important memories. The voice should honor that weight without becoming precious about it. Influences: the way Magnum Photos writes about their work. The directness of a good photo caption. Not the breathless enthusiasm of a SaaS landing page. The document should include: - Core personality traits (3–4, with explanation) - Tone spectrum (when to be warmer vs. more spare) - Vocabulary: words we use, words we avoid - UI microcopy examples (button labels, empty states, error messages) - Both Spanish and English examples side by side </code></pre></div></div> <p>This second prompt goes straight to the character of the app. A brand voice guide is a document that rarely gets produced in an MVP phase — and it’s one of the most useful when the time comes to write microcopy or define how the app speaks to its users.</p> <hr /> <h3 id="prompt-3--ui-mocks">Prompt 3 — UI Mocks</h3> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Using the frontend-design skill, create UI mocks for Liminal's critical screens. Pull from the brand guide already established and the brand voice: quiet craft, deliberate, editorial — not SaaS. Prioritize these screens in order: Client-facing (unauthenticated, via share link): 1. Gallery landing — the first thing a client sees when they open their link. 2. Collection view — browsing photos within a collection, with like, comment, and download interactions visible. 3. Download selection — choosing photos and quality before downloading as zip. Photographer-facing (authenticated): 4. Project dashboard — list of projects with status at a glance. 5. Collection editor — uploading photos, reordering, setting cover photo. 6. Share link manager — creating and tracking links, seeing which have been used. For each screen: - Design for desktop first, note mobile considerations - Show real placeholder content — no Lorem Ipsum - Embed a short design rationale note explaining the key decision made for that screen Aesthetic direction: editorial photography magazine meets quiet utility. The UI should feel like it was designed by someone who photographs, not someone who ships dashboards. </code></pre></div></div> <p>The third prompt uses the <code class="highlighter-rouge">frontend-design</code> skill together with <a href="https://maquina.app/documentation/components/">Maquina Components</a> to generate HTML mocks of the critical screens. The result isn’t a Figma file — it’s a functional visual reference, coherent with the brand guide, before opening the editor.</p> <hr /> <h2 id="the-result">The Result</h2> <p>Three prompts. Six documents. Mocks of the main screens. All the context needed to hand off to Claude Code and start generating code with direction.</p> <p>It’s the same process I used to build <a href="https://turesto.app/en">Resto</a>, a personal finance app based on the Japanese Kakeibo method.</p> <p>The video runs 40 minutes. It’s not an accelerated demo — it’s the real process, iterations and corrections included.</p> <hr /> <h2 id="installation">Installation</h2> <p>All plugins are available in the <a href="https://github.com/maquina-app/rails-claude-code">maquina-app/rails-claude-code</a> repository. Full documentation at <a href="/documentation/ai-tools/mvp-creator/">MVP Creator — Documentation</a>.</p> <p>To install MVP Creator in Claude Code:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Add the marketplace</span> /plugin marketplace add maquina-app/rails-claude-code <span class="c"># Install the plugin</span> /plugin <span class="nb">install </span>mvp-creator@maquina </code></pre></div></div> <p>To install the full set of plugins used in this series:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>/plugin <span class="nb">install </span>rails-simplifier@maquina /plugin <span class="nb">install </span>rails-upgrade-assistant@maquina /plugin <span class="nb">install </span>maquina-ui-standards@maquina /plugin <span class="nb">install </span>mvp-creator@maquina /plugin <span class="nb">install </span>better-stimulus@maquina /plugin <span class="nb">install </span>spec-driven-development@maquina </code></pre></div></div> <p>For the Claude graphical interface, download the repository as a zip, extract the <code class="highlighter-rouge">mvp-creator</code> folder, rename the extension to <code class="highlighter-rouge">.skill</code>, and drag it into the Claude window to install it.</p>Mario Alberto Chávez Cárdenas