Bridgetown2026-04-16T15:39:50-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-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/announcing-recuerd0/">Announcing Recuerd0</a> — the original launch and the problem we set out to solve.</li> <li><a href="/blog/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árdenas2026-03-13T00:00:00-06:002026-03-13T00:00:00-06:00repo://posts.collection/_posts/2026-03-13-maquina-generators-production-ready-rails-setup.md<p>Every Rails project starts the same way. You run <code class="highlighter-rouge">rails new</code>, you get a clean app with sensible defaults, and then you do the setup work before you can write application code. Authentication with signup and multi-tenancy. Rate limiting. Background jobs with a dashboard. Error tracking. Mailer templates. Security headers. It’s repetitive, sure, but it’s the work that gets your app to the point where you can build the thing you actually sat down to build.</p> <p>I’ve done this enough times to know exactly what’s coming. The order changes, the names of the models drift slightly, but the shape of the work is identical. It’s not that Rails is missing anything — it’s that the space between <code class="highlighter-rouge">rails new</code> and “ready to build features” is full of choices that are mostly already made. You just have to type them out each time.</p> <p>Maquina Generators automate that setup. One command after <code class="highlighter-rouge">rails new</code>, and you have authentication, multi-tenancy, roles, job processing, error tracking, request protection, and ops dashboards. All generated into your app as plain Rails code. No runtime dependency.</p> <h2 id="what-maquina-generators-do">What Maquina Generators Do</h2> <p>The gem lives in your development group. It generates standalone application code — models, controllers, views, migrations, initializers, mailers — and then you can delete the gem. Nothing it produces requires the gem at runtime. No engine mounts, no middleware injection, no monkey patches. Just files in your app that you own completely.</p> <p>The workflow is five commands:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>rails new myapp <span class="nt">--css</span> tailwind bundle add maquina-generators <span class="nt">--group</span> development rails generate maquina:app <span class="nt">--auth</span> clave bin/rails db:migrate bin/dev </code></pre></div></div> <p>That’s it. Auth with email verification codes, an Account model with roles, Rack Attack blocking scanners and throttling logins, Solid Queue with a Procfile, Solid Errors catching exceptions, Mission Control monitoring your jobs — all wired up, all running.</p> <p><img src="/images/blog/generators-screenshot-1.png" alt="Generated app homepage showing authentication, background jobs, error tracking, rate limiting, caching, and real-time features" /></p> <p>Seven generators handle the pieces:</p> <table> <thead> <tr> <th>Generator</th> <th>Purpose</th> </tr> </thead> <tbody> <tr> <td><strong>App</strong></td> <td>Full application setup — orchestrates everything below</td> </tr> <tr> <td><strong>Clave</strong></td> <td>Passwordless email-code authentication</td> </tr> <tr> <td><strong>Registration</strong></td> <td>Password-based auth with accounts and roles</td> </tr> <tr> <td><strong>Rack Attack</strong></td> <td>Request protection and IP throttling</td> </tr> <tr> <td><strong>Solid Queue</strong></td> <td>Background job processing with separate database</td> </tr> <tr> <td><strong>Solid Errors</strong></td> <td>Error tracking dashboard</td> </tr> <tr> <td><strong>Mission Control</strong></td> <td>Job queue monitoring dashboard</td> </tr> </tbody> </table> <p>The App generator is the orchestrator. It runs whichever auth generator you choose, then all the infrastructure generators in sequence. You can also run each generator independently if you only need part of the stack.</p> <p>The <a href="/documentation/generators/">full documentation</a> covers every generator, option, and generated file in detail.</p> <h2 id="two-authentication-options">Two Authentication Options</h2> <p>Rails 8’s built-in <code class="highlighter-rouge">rails generate authentication</code> gives you login. It doesn’t give you signup. It doesn’t give you accounts, roles, or multi-tenancy. For most applications, login alone isn’t enough.</p> <p>Maquina Generators offer two complete authentication systems that pick up where Rails leaves off.</p> <h3 id="clave-passwordless">Clave: Passwordless</h3> <p>Clave implements passwordless authentication using email verification codes. The user enters their email, receives a 6-digit hexadecimal code, enters the code, and they’re in. No passwords to store, no password resets to build, no complexity requirements to argue about.</p> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>User enters email → receives 6-digit code → enters code → signed in </code></pre></div></div> <p>Codes expire in 15 minutes. There’s a 15-minute cooldown before a resend. Login attempts are rate-limited to 10 per 3 minutes. Sessions last 30 days by default. Plus characters are blocked in email addresses to prevent alias attacks.</p> <p>Beyond sign-in, Clave generates a full multi-tenancy layer. Every user belongs to an Account. The first user who creates an account becomes its admin. A role enum — admin or member — handles authorization from there.</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="no">Current</span><span class="p">.</span><span class="nf">user</span> <span class="c1"># The signed-in user</span> <span class="no">Current</span><span class="p">.</span><span class="nf">account</span> <span class="c1"># The user's account</span> <span class="no">Current</span><span class="p">.</span><span class="nf">user</span><span class="p">.</span><span class="nf">admin?</span> <span class="c1"># Check role</span> </code></pre></div></div> <p>You scope queries through the account, and cross-tenant access is prevented at the model level:</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="vi">@projects</span> <span class="o">=</span> <span class="no">Current</span><span class="p">.</span><span class="nf">account</span><span class="p">.</span><span class="nf">projects</span> </code></pre></div></div> <p>Clave generates models, controllers, a mailer with HTML and text templates, a daily cleanup job for expired sessions and codes, a test helper with <code class="highlighter-rouge">sign_in_as(user)</code>, and full i18n support in English and Spanish.</p> <h3 id="registration-password-based">Registration: Password-Based</h3> <p>If you prefer passwords, the Registration generator builds on Rails 8’s authentication. It runs <code class="highlighter-rouge">rails generate authentication</code> first, then adds what’s missing: an Account model, <code class="highlighter-rouge">belongs_to :account</code> on User, the role enum, a RegistrationsController that creates an Account and User in a single transaction, and Tailwind-styled views.</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">class</span> <span class="nc">RegistrationsController</span> <span class="o">&lt;</span> <span class="no">ApplicationController</span> <span class="n">allow_unauthenticated_access</span> <span class="n">rate_limit</span> <span class="ss">to: </span><span class="mi">10</span><span class="p">,</span> <span class="ss">within: </span><span class="mi">3</span><span class="p">.</span><span class="nf">minutes</span><span class="p">,</span> <span class="ss">only: :create</span> <span class="k">def</span> <span class="nf">create</span> <span class="no">ActiveRecord</span><span class="o">::</span><span class="no">Base</span><span class="p">.</span><span class="nf">transaction</span> <span class="k">do</span> <span class="n">account</span> <span class="o">=</span> <span class="no">Account</span><span class="p">.</span><span class="nf">create!</span><span class="p">(</span><span class="ss">name: </span><span class="n">params</span><span class="p">[</span><span class="ss">:account_name</span><span class="p">])</span> <span class="n">user</span> <span class="o">=</span> <span class="n">account</span><span class="p">.</span><span class="nf">users</span><span class="p">.</span><span class="nf">create!</span><span class="p">(</span> <span class="ss">name: </span><span class="n">params</span><span class="p">[</span><span class="ss">:name</span><span class="p">],</span> <span class="ss">email_address: </span><span class="n">params</span><span class="p">[</span><span class="ss">:email_address</span><span class="p">],</span> <span class="ss">password: </span><span class="n">params</span><span class="p">[</span><span class="ss">:password</span><span class="p">],</span> <span class="ss">role: :admin</span> <span class="p">)</span> <span class="k">end</span> <span class="n">start_new_session_for</span> <span class="n">user</span> <span class="n">redirect_to</span> <span class="n">root_path</span> <span class="k">end</span> <span class="k">end</span> </code></pre></div></div> <p><img src="/images/blog/generators-screenshot-2.png" alt="Generated sign-in page with email and password fields" /></p> <p>Same <code class="highlighter-rouge">Current.user</code>, <code class="highlighter-rouge">Current.account</code>, and role-based authorization as Clave. The multi-tenancy pattern is identical — only the sign-in mechanism differs.</p> <p>The <a href="/documentation/generators/">generators documentation</a> covers every option, model, and controller for both auth systems.</p> <h2 id="the-ops-layer">The Ops Layer</h2> <p>Authentication is the most visible piece, but the App generator does more than auth. It sets up a complete operational layer that most Rails apps need but few have on day one.</p> <p><strong>Rack Attack</strong> gets configured with real-world defaults. PHP file requests, WordPress scanning paths, <code class="highlighter-rouge">.env</code> and <code class="highlighter-rouge">.git</code> probes — all blocked immediately. Sensitive paths like <code class="highlighter-rouge">/cgi-bin</code>, <code class="highlighter-rouge">/phpmyadmin</code>, and <code class="highlighter-rouge">/actuator</code> return 403. General traffic is throttled to 300 requests per 5 minutes per IP, with asset paths exempted. Login endpoints get tighter limits: 5 attempts per 20 seconds.</p> <p><strong>Solid Queue</strong> is set up as the Active Job backend with its own SQLite database, a Procfile entry for the worker process, and a recurring schedule that runs the authentication cleanup job daily at 3am. The configuration lives in <code class="highlighter-rouge">config/solid_queue.yml</code> — three worker threads, half-second polling, standard dispatching.</p> <p><strong>Solid Errors</strong> and <strong>Mission Control Jobs</strong> get mounted as dashboards with custom Tailwind views. Mission Control alone has 41 view files — job listings, queue status, worker monitoring, recurring task management — all styled to match your application instead of looking like a default engine mount.</p> <p>Both dashboards share the same HTTP basic auth credentials:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># bin/rails credentials:edit</span> <span class="na">backstage</span><span class="pi">:</span> <span class="na">username</span><span class="pi">:</span> <span class="s">admin</span> <span class="na">password</span><span class="pi">:</span> <span class="s">your_secure_password</span> </code></pre></div></div> <p>One set of credentials, stored in Rails credentials. Environment variable fallbacks if you prefer. After running the generators, you have <code class="highlighter-rouge">/admin/solid_errors</code> and <code class="highlighter-rouge">/admin/mission_control_jobs</code> working from the first <code class="highlighter-rouge">bin/dev</code>.</p> <p><img src="/images/blog/generators-screenshot-3.png" alt="Admin tools section showing Solid Errors and Mission Control Jobs dashboards after sign-in" /></p> <p>The App generator also sets up multi-database configuration — separate SQLite databases for the queue, cache, cable, and errors — installs Active Storage and Action Text, configures Turbo morphing, adds brakeman and Standard for code quality, and creates a HomeController with a root route. It’s the full post-<code class="highlighter-rouge">rails new</code> checklist, automated.</p> <h2 id="own-the-code">Own the Code</h2> <p>This is the part that matters most. Maquina Generators is a development-only gem. It generates code into your application and then it’s done. You can — and should — delete it from your Gemfile once you’ve run the generators.</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Gemfile — remove after generating</span> <span class="n">group</span> <span class="ss">:development</span> <span class="k">do</span> <span class="n">gem</span> <span class="s2">"maquina-generators"</span> <span class="k">end</span> </code></pre></div></div> <p>Every file it produces is a standard Rails file in a standard location. Models in <code class="highlighter-rouge">app/models</code>, controllers in <code class="highlighter-rouge">app/controllers</code>, views in <code class="highlighter-rouge">app/views</code>, initializers in <code class="highlighter-rouge">config/initializers</code>. No engine, no namespace, no gem dependency at runtime. If you want to change how sessions expire, you edit <code class="highlighter-rouge">app/controllers/concerns/authentication.rb</code>. If you want different Rack Attack rules, you edit <code class="highlighter-rouge">config/initializers/rack_attack.rb</code>. If you want to add a third role beyond admin and member, you update the enum on User.</p> <p>There’s no DSL to learn, no configuration file to maintain, no version upgrades to track. The generated code follows Rails conventions because it <em>is</em> Rails code. You can read every line, understand every decision, and change anything that doesn’t fit your project.</p> <p>This connects to the broader Maquina ecosystem. The generators set up the foundation — auth, security, ops tooling. <a href="/documentation/components/">Maquina Components</a> handles the UI layer with ViewComponent-based partials that the App generator installs automatically. When you start building features on top of this foundation, <a href="/documentation/ai-tools/rails-simplifier/">Rails Simplifier</a> keeps AI-generated code idiomatic, and the <a href="/documentation/ai-tools/rails-mcp-server/">MCP Server</a> gives AI tools visibility into your codebase structure.</p> <p>Each tool is independent. Use one, use all, use none. No lock-in at any layer.</p> <h2 id="get-started">Get Started</h2> <p>Install the gem and run the app generator:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>rails new myapp <span class="nt">--css</span> tailwind <span class="nb">cd </span>myapp bundle add maquina-generators <span class="nt">--group</span> development rails generate maquina:app <span class="nt">--auth</span> clave bin/rails db:migrate bin/dev </code></pre></div></div> <p>Choose <code class="highlighter-rouge">--auth clave</code> for passwordless, <code class="highlighter-rouge">--auth registration</code> for passwords, or <code class="highlighter-rouge">--auth none</code> if you want the infrastructure without authentication.</p> <p>Full documentation is at <a href="/documentation/generators/">maquina.app/documentation/generators</a>. Source code is on <a href="https://github.com/maquina-app/maquina_generators">GitHub</a>.</p>Mario Alberto Chávez Cárdenas2026-02-21T00:00:00-06:002026-02-21T00:00:00-06:00repo://posts.collection/_posts/2026-02-21-recuerd0-source-code-now-available.md<p><em>The self-hosted promise is fulfilled — Recuerd0’s source code is on GitHub.</em></p> <hr /> <p>When we <a href="/blog/2026/02/15/announcing-recuerd0/">announced Recuerd0</a>, we said the self-hosted version would be available pretty soon. Today it is. The full source code is on <a href="https://github.com/maquina-app/recuerd0">GitHub</a> under the OSASSY license.</p> <p>This is not a stripped-down edition. It’s the same codebase that runs <a href="https://recuerd0.ai/">recuerd0.ai</a> — every feature, every endpoint, every migration.</p> <h2 id="under-the-hood">Under the hood</h2> <p>Recuerd0 is a Rails 8.1 application running on Ruby 4.0. The entire stack leans into the One Person Framework philosophy: minimize infrastructure, eliminate external dependencies, ship with confidence.</p> <p><strong>SQLite for everything.</strong> Data, cache, queue, and cable — all backed by SQLite. No Postgres. No Redis. Solid Queue handles background jobs, Solid Cache handles caching, and Solid Cable handles WebSocket connections. One database engine, zero extra services.</p> <p><strong>No Node.js.</strong> The frontend uses Propshaft for asset delivery and Importmaps for JavaScript modules. Hotwire (Turbo + Stimulus) handles interactivity. Tailwind CSS 4 handles styling. The entire frontend pipeline runs without a JS build step.</p> <p><strong>Full-text search with FTS5.</strong> Search is powered by SQLite’s FTS5 extension — no vector database, no embeddings, no RAG pipeline. The index updates on every write, returns results in milliseconds, and is fully deterministic. The agent decides what to search for; the database does the rest.</p> <p><strong>Memory versioning.</strong> Every memory supports a flat branching model — create new versions from any point in history. Soft deletion with 30-day retention means nothing disappears by accident.</p> <p><strong>Multi-tenancy.</strong> The Account model supports multiple tenants. In single-tenant mode (the default for self-hosted), public registration is disabled — you control who has access.</p> <p><strong>UI components.</strong> The interface is built with the <a href="https://github.com/maquina-app/maquina_components">maquina-components</a> gem, the same component library used across all Maquina projects.</p> <h2 id="getting-started">Getting started</h2> <p>Two paths to self-host:</p> <p><strong>Docker image.</strong> Pull the ready-to-use Docker image and deploy. Configure your environment variables and you’re running.</p> <p><strong>From source.</strong> Clone the <a href="https://github.com/maquina-app/recuerd0">repository</a>, configure Kamal 2.x, and deploy to your server. The included Dockerfile and Kamal configuration handle the rest. Thruster sits in front of Puma, and <code class="highlighter-rouge">SOLID_QUEUE_IN_PUMA=true</code> runs background jobs in-process — one container, one process, everything included.</p> <p>Single-tenant mode is the default. No public registration, no setup wizard. Deploy, create your account, start curating context.</p> <h2 id="license">License</h2> <p>Recuerd0 is released under the <a href="https://osaasy.dev/">OSASSY license</a>. It’s essentially MIT with one restriction: you can’t take the code and offer it as a competing hosted service. The same model 37signals uses. Deploy it on your infrastructure, modify it, use it internally — free forever.</p> <h2 id="not-interested-in-self-hosting">Not interested in self-hosting?</h2> <p><a href="https://recuerd0.ai/">Recuerd0 SaaS</a> is $15/month for up to 10 users — managed hosting, automatic backups, and updates. Read the <a href="/blog/2026/02/15/announcing-recuerd0/">full product announcement</a> for the complete story.</p> <p>The source is on GitHub. Do what you want with it.</p> <p><a href="https://github.com/maquina-app/recuerd0">View the repository →</a></p> <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-02-15T00:00:00-06:002026-02-15T00:00:00-06:00repo://posts.collection/_posts/2026-02-15-announcing-recuerd0.md<p><em>Organize, version, and serve project context to any LLM — from Claude Code to Cursor to ChatGPT.</em></p> <hr /> <p>Every AI coding tool starts each session with amnesia. Your architecture decisions, naming conventions, and deployment quirks — none of it carries over. You re-explain the same context with the same tools every single day.</p> <p>The common workarounds are CLAUDE.md files, .cursorrules, AGENTS.md — each tool with its own configuration format. You end up duplicating knowledge across multiple places. They drift apart. Your Claude Code config says one thing; your Cursor rules say another.</p> <p>Recuerd0 is a dedicated knowledge base for managing the context your AI tools consume. You curate project knowledge once and serve it to every tool via REST API.</p> <p><img src="/images/recuerd0/home-01.png" alt="Recuerd0 homepage — the knowledge base your AI tools deserve" /></p> <h2 id="how-it-works">How it works</h2> <p><strong>Workspaces</strong> group knowledge by project or domain. Backend conventions in one workspace, frontend patterns in another, org-wide standards in a shared workspace.</p> <p><img src="/images/recuerd0/workspaces-02.png" alt="Workspace view showing pinned memories with tags and descriptions" /></p> <p><strong>Memories</strong> are versioned markdown documents with titles, tags, and full history. When conventions evolve, you create a new version — like Git for context. Branch from any version, track how decisions changed, and never lose the rationale.</p> <p><img src="/images/recuerd0/memory-03.png" alt="Memory detail showing rendered markdown content with version history and tags" /></p> <p><strong>Access</strong> is through a REST API with Bearer token authentication. Any tool that can make an HTTP request reads from the same source. There’s also a CLI for terminal workflows and a Claude Code plugin for tighter integration.</p> <p>Search uses the database’s full-text search with millisecond performance. No embeddings, no vector database, no RAG pipeline. The agent decides what to search for and how to refine the search. The index updates on every write, is deterministic, and requires zero infrastructure beyond the database.</p> <h2 id="architecture-decisions">Architecture decisions</h2> <p><strong>Human-curated, not auto-captured.</strong> Automatic knowledge capture sounds appealing, but it produces noisy results — context-specific fixes that don’t generalize, contradictory items as conventions evolve. The human decides what’s worth persisting. The team reviews and evolves it.</p> <p><strong>Tool-agnostic by design.</strong> We built an API, not a plugin for one tool. Your knowledge base survives any tool change. Claude Code, Cursor, ChatGPT, Windsurf, custom scripts, CI/CD pipelines — same context, same source.</p> <p><strong>Small and focused.</strong> Recuerd0 is designed for a small set of focused memories per workspace philosophy, not thousands of files. The constraint forces curation. When the workspace is focused, the right answer is obvious without sophisticated search algorithms.</p> <h2 id="pricing">Pricing</h2> <p><strong>Recuerd0 SaaS</strong> is $15/month for up to 10 users. Managed hosting, automatic backups, updates, and email support. Create an account and start in minutes at <a href="https://recuerd0.ai/">recuerd0.ai</a>.</p> <p>Teams of 6 or more can contact us for custom plans.</p> <p><strong>Self-hosted</strong> is available under the <a href="https://osaasy.dev/">OSASSY license</a> — the same model 37signals uses for Fizzy. It’s essentially MIT with one addition: you can’t take the code and offer it as a competing hosted service. Deploy on your server, modify the code, use it internally — free forever.</p> <p>The self-hosted version is not available at launch, but it will be available pretty soon.</p> <h2 id="get-started">Get started</h2> <p>The <a href="https://recuerd0.ai/api-docs">API documentation</a> covers every endpoint. The <a href="https://recuerd0.ai/cli">CLI reference</a> has installation and commands. The <a href="https://recuerd0.ai/agents">agent workflows guide</a> shows how to integrate with Claude Code, Cursor, and other tools.</p> <p>Context engineering has become a core developer skill. It deserves a dedicated tool.</p> <p><a href="https://recuerd0.ai/">Start with Recuerd0 SaaS →</a></p> <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-02-13T00:00:00-06:002026-02-13T00:00:00-06:00repo://posts.collection/_posts/2026-02-13-maquina-components-0-4-0-turbo-compatibility.md<p>I was working on a Rails application—standard CRUD with a sidebar and a few interactive menus. Everything worked on first load. Then I navigated away and came back. The sidebar was gone. I opened a dropdown, clicked a Turbo link, hit the back button. The dropdown was still open, sitting there on top of a page that had already moved on.</p> <p>If you’ve built anything with Turbo and Stimulus beyond basic forms, you’ve likely seen this. Components work fine on full page loads, but Turbo introduces a different lifecycle. Pages get cached mid-state, morphs overwrite client-side changes with stale server HTML, and your UI ends up stuck in states it should have left behind.</p> <p>Fixing this in <a href="/documentation/components/">Maquina Components</a> is what version 0.4.0 is about.</p> <h2 id="the-teardown-pattern">The Teardown Pattern</h2> <p>The core problem is described well by <a href="https://betterstimulus.com/turbo/teardown">Better Stimulus</a>. When Turbo navigates away from a page, it takes a snapshot of the DOM before leaving. When the user returns, Turbo shows that snapshot first. Any DOM changes your Stimulus controllers made—open menus, expanded panels, loading classes—get frozen into the cache.</p> <p>The standard Stimulus <code class="highlighter-rouge">disconnect</code> callback handles general cleanup, but it doesn’t distinguish between “the element was removed from the DOM” and “Turbo is about to cache this page.” You need both.</p> <p>The Teardown pattern adds a <code class="highlighter-rouge">teardown</code> method to controllers, triggered by Turbo’s <code class="highlighter-rouge">turbo:before-cache</code> event. Every controller that manipulates the DOM can opt in, resetting its visual state before Turbo takes the snapshot. This keeps <code class="highlighter-rouge">disconnect</code> clean for general lifecycle concerns and gives Turbo-specific rollback its own dedicated path.</p> <p>This release applies that pattern across the interactive components in the library.</p> <h2 id="sidebar-three-problems-at-once">Sidebar: Three Problems at Once</h2> <p>The sidebar was the hardest to get right. It had three separate issues interacting with each other.</p> <p><strong>Random IDs broke morphing.</strong> The sidebar generated IDs like <code class="highlighter-rouge">sidebar-a3f9b2</code> on every render. Turbo’s idiomorph algorithm matches elements by ID—when the ID changes every time, idiomorph can’t find the element and treats it as new. Every morph was destroying and recreating the sidebar from scratch. The fix: deterministic IDs. <code class="highlighter-rouge">sidebar-left</code> and <code class="highlighter-rouge">sidebar-right</code>, consistent across renders. The sidebar provider also gets a stable ID (<code class="highlighter-rouge">sidebar-provider</code> by default).</p> <p><strong>Morphs overwrote client state.</strong> The sidebar stores its open/closed state in a cookie so it persists across page loads. During a Turbo morph, the server sends back HTML with the default state—it doesn’t know about the cookie. Idiomorph applies the server HTML, and the sidebar collapses even though the user had it open.</p> <p>The fix adds a <code class="highlighter-rouge">turbo:before-morph-element</code> listener with a <code class="highlighter-rouge">_morphing</code> guard flag. When a morph happens, the controller reads the cookie (the source of truth on the client), reasserts the correct state, and strips the <code class="highlighter-rouge">sidebar-loading</code> class that the server HTML reintroduces.</p> <p><strong>Layout shift on desktop.</strong> When Stimulus initialized and switched the sidebar from its mobile offcanvas mode to the desktop collapsible mode, there was a visible jump. The transition happened after the browser had already painted. This release smooths that handoff so the mode switch doesn’t cause a flash.</p> <h2 id="the-yield-trap">The Yield Trap</h2> <p>The second category of fixes has nothing to do with Turbo. It’s a Rails rendering behavior that caught me off guard.</p> <p>Nine partials in the library used the standard block pattern:</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/card/description"</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="nt">&lt;p&gt;</span>Custom HTML<span class="nt">&lt;/p&gt;</span> <span class="cp">&lt;%</span> <span class="k">end</span> <span class="cp">%&gt;</span> </code></pre></div></div> <p>This works when you always pass a block. But render the partial <em>without</em> a block and <code class="highlighter-rouge">yield</code> inside it doesn’t return nothing—it renders the entire page’s content into the partial. Rails treats the missing block as a signal to yield the page-level content instead.</p> <p>The result: components rendering the full page body inside a card title or a toast message. It only shows up in specific usage patterns, and when it does, the output looks completely wrong with no obvious cause.</p> <p>The fix replaces <code class="highlighter-rouge">yield</code> with an explicit <code class="highlighter-rouge">content:</code> parameter in all nine affected partials:</p> <ul> <li>card/title, card/description</li> <li>alert/title, alert/description</li> <li>toast/title, toast/description</li> <li>combobox/label, toast (main), toaster</li> </ul> <p>The five toast helper methods no longer accept blocks either.</p> <h2 id="breaking-changes">Breaking Changes</h2> <p>This is a minor version bump with breaking changes:</p> <ul> <li><strong>Block syntax removed</strong> for the 9 partials listed above. Use <code class="highlighter-rouge">content: capture { ... }</code> instead of <code class="highlighter-rouge">do ... end</code>.</li> <li><strong>Toast helpers</strong> no longer accept blocks. Use the <code class="highlighter-rouge">content:</code> parameter.</li> <li><strong>Sidebar IDs</strong> changed from <code class="highlighter-rouge">sidebar-&lt;random_hex&gt;</code> to <code class="highlighter-rouge">sidebar-left</code> / <code class="highlighter-rouge">sidebar-right</code>.</li> <li><strong>Sidebar provider</strong> now has a stable <code class="highlighter-rouge">id</code> attribute (<code class="highlighter-rouge">sidebar-provider</code> by default).</li> </ul> <h2 id="migration">Migration</h2> <p>The content parameter change is mechanical. Find every block-style call to the affected partials and wrap the content with <code class="highlighter-rouge">capture</code>:</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/card/description"</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="nt">&lt;p&gt;</span>Custom HTML<span class="nt">&lt;/p&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/card/description"</span><span class="p">,</span> <span class="ss">content: </span><span class="n">capture</span> <span class="p">{</span> <span class="cp">%&gt;</span> <span class="nt">&lt;p&gt;</span>Custom HTML<span class="nt">&lt;/p&gt;</span> <span class="cp">&lt;%</span> <span class="p">}</span> <span class="cp">%&gt;</span> </code></pre></div></div> <p>For sidebar IDs, if you reference specific sidebar element IDs in JavaScript or tests, update them to <code class="highlighter-rouge">sidebar-left</code> or <code class="highlighter-rouge">sidebar-right</code>.</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> <h2 id="what-this-reinforced">What This Reinforced</h2> <p>Turbo is not a transparent layer over page loads. It’s a different execution model. Any Stimulus controller that touches the DOM needs to account for caching, morphing, and the gap between what the server renders and what the client has changed since. The <a href="https://betterstimulus.com/turbo/teardown">Teardown pattern</a> should be the default starting point for any controller that does more than read values.</p> <p>The <code class="highlighter-rouge">yield</code> behavior in Rails partials was a genuine surprise. It’s documented, but it’s a quiet trap when you have optional block content. Explicit parameters are safer.</p> <h2 id="documentation">Documentation</h2> <ul> <li><a href="https://maquina.app/documentation/components/">Component Documentation</a></li> <li><a href="https://maquina.app/documentation/components/sidebar/">Sidebar</a></li> <li><a href="https://maquina.app/documentation/components/card/">Card</a></li> <li><a href="https://maquina.app/documentation/components/alert/">Alert</a></li> <li><a href="https://maquina.app/documentation/components/toast/">Toast</a></li> <li><a href="https://maquina.app/documentation/components/combobox/">Combobox</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.3.1.1...v0.4.0">Full Changelog</a></li> <li><a href="https://betterstimulus.com/turbo/teardown">Better Stimulus: Teardown Pattern</a></li> </ul>Mario Alberto Chávez Cárdenas2026-01-23T00:00:00-06:002026-01-23T00:00:00-06:00repo://posts.collection/_posts/2026-01-23-maquina-0-3-1-calendar-date-picker-claude-skills.md<p>This month brings updates across the Maquina ecosystem: new Calendar and Date Picker components for Rails, two Claude Code skills for AI-assisted development, and live interactive previews for all components in the documentation.</p> <h2 id="maquina-components-031">Maquina Components 0.3.1</h2> <p>Building on <a href="/blog/2026/01/maquina-components-0.3.0-combobox-and-toast/">version 0.3.0</a>, this release adds two components for date selection: <strong>Calendar</strong> and <strong>Date Picker</strong>.</p> <h3 id="calendar">Calendar</h3> <p>An inline calendar for single date or range selection. Useful when you need the full calendar visible—booking flows, availability displays, or any context where date proximity matters.</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/calendar"</span><span class="p">,</span> <span class="ss">mode: :range</span><span class="p">,</span> <span class="ss">selected: </span><span class="no">Date</span><span class="p">.</span><span class="nf">today</span><span class="p">,</span> <span class="ss">selected_end: </span><span class="no">Date</span><span class="p">.</span><span class="nf">today</span> <span class="o">+</span> <span class="mi">5</span> <span class="cp">%&gt;</span> </code></pre></div></div> <p>For form integration, the calendar generates hidden inputs automatically:</p> <div class="language-erb highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;%=</span> <span class="n">form_with</span> <span class="ss">model: </span><span class="vi">@booking</span> <span class="k">do</span> <span class="o">|</span><span class="n">f</span><span class="o">|</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%=</span> <span class="n">render</span> <span class="s2">"components/calendar"</span><span class="p">,</span> <span class="ss">mode: :range</span><span class="p">,</span> <span class="ss">input_name: </span><span class="s2">"booking[check_in]"</span><span class="p">,</span> <span class="ss">input_name_end: </span><span class="s2">"booking[check_out]"</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><strong>Features:</strong> Single or range selection, min/max date constraints, disabled dates, week start configuration, and direct form integration with hidden inputs.</p> <h3 id="date-picker">Date Picker</h3> <p>A button that opens a calendar in a popover. Better for forms where space is limited and you don’t need the calendar always visible.</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/date_picker"</span><span class="p">,</span> <span class="ss">mode: :single</span><span class="p">,</span> <span class="ss">placeholder: </span><span class="s2">"Select a date"</span><span class="p">,</span> <span class="ss">input_name: </span><span class="s2">"event[date]"</span> <span class="cp">%&gt;</span> </code></pre></div></div> <p>Range selection works the same way:</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/date_picker"</span><span class="p">,</span> <span class="ss">mode: :range</span><span class="p">,</span> <span class="ss">placeholder: </span><span class="s2">"Select date range"</span><span class="p">,</span> <span class="ss">input_name: </span><span class="s2">"start_date"</span><span class="p">,</span> <span class="ss">input_name_end: </span><span class="s2">"end_date"</span> <span class="cp">%&gt;</span> </code></pre></div></div> <p><strong>Features:</strong> Single or range selection, pre-selected date display, min/max boundaries, disabled state, and customizable placeholders.</p> <h3 id="when-to-use-which">When to Use Which</h3> <table> <thead> <tr> <th>Use Case</th> <th>Component</th> </tr> </thead> <tbody> <tr> <td>Booking calendar with visible availability</td> <td>Calendar</td> </tr> <tr> <td>Date field in a form</td> <td>Date Picker</td> </tr> <tr> <td>Date range with context (prices, events)</td> <td>Calendar</td> </tr> <tr> <td>Quick date selection in limited space</td> <td>Date Picker</td> </tr> </tbody> </table> <h3 id="live-previews">Live Previews</h3> <p><img src="/images/components/components-green.png" alt="Maquina Components live previews showing components in green theme" /></p> <p>The documentation site now includes live, interactive previews for all components. Visit any component page in the <a href="/documentation/components/">documentation</a> to see working examples in light and dark themes, multiple color variations, and code ready to copy.</p> <p>For a complete showcase, the <a href="https://demo.maquina.app">live demo application</a> shows all components working together with sample data.</p> <h3 id="upgrading">Upgrading</h3> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bundle update maquina_components </code></pre></div></div> <p>No generator changes required for existing installations.</p> <h2 id="claude-code-skills">Claude Code Skills</h2> <p>Two new skills for AI-assisted Rails development.</p> <h3 id="maquina-ui-standards">Maquina UI Standards</h3> <p>Teaches Claude how to build UIs with <code class="highlighter-rouge">maquina_components</code>. Without guidance, Claude generates generic Rails patterns—plain divs, inline styles, inconsistent markup. With this skill, Claude generates code using your actual component library.</p> <p><strong>Includes:</strong> Component catalog with 20+ components, form patterns, layout patterns, Turbo integration, and accessibility guidelines.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>/plugin marketplace add maquina-app/rails-claude-code /plugin <span class="nb">install </span>maquina-ui-standards@maquina </code></pre></div></div> <p>Ask Claude <em>“Create a users index view with a table”</em> and get:</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/card"</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/card/header"</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/card/title"</span><span class="p">,</span> <span class="ss">text: </span><span class="s2">"Users"</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/card/content"</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/table"</span> <span class="k">do</span> <span class="o">|</span><span class="n">t</span><span class="o">|</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="n">t</span><span class="p">.</span><span class="nf">header</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="n">t</span><span class="p">.</span><span class="nf">head_cell</span> <span class="s2">"Name"</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="n">t</span><span class="p">.</span><span class="nf">head_cell</span> <span class="s2">"Email"</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> <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>Documentation: <a href="/documentation/ai-tools/maquina-ui-standards/">Maquina UI Standards</a></p> <h3 id="rails-simplifier">Rails Simplifier</h3> <p>Refines Rails code following 37signals patterns and the One Person Framework philosophy.</p> <p><strong>What it does:</strong> Converts service objects to model methods, transforms custom actions to CRUD resources, moves logic from controllers to models, detects N+1 queries, and applies Rails conventions like I18n and Time.current.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>/plugin marketplace add maquina-app/rails-claude-code /plugin <span class="nb">install </span>rails-simplifier@maquina </code></pre></div></div> <p>Example prompts:</p> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&gt; Review recent changes using the rails-simplifier agent &gt; Use rails-simplifier to review the bookings controller </code></pre></div></div> <p>Documentation: <a href="/documentation/ai-tools/rails-simplifier/">Rails Simplifier</a></p> <h2 id="source">Source</h2> <p>All projects are MIT licensed:</p> <ul> <li><a href="https://github.com/maquina-app/maquina_components">Maquina Components</a></li> <li><a href="https://github.com/maquina-app/rails-claude-code">Rails Claude Code Skills</a></li> </ul>Mario Alberto Chávez Cárdenas2026-01-08T00:00:00-06:002026-01-08T00:00:00-06:00repo://posts.collection/_posts/2026-01-08-maquina-ui-standards-skill.md<p>When I started extracting and standardizing <a href="/blog/announcing-maquina-components/">maquina_components</a> from real production applications, I was also experimenting with AI-assisted development. The two efforts ran in parallel—building a consistent component library while trying to get Claude to help me use it.</p> <p>The results were mixed. Every time I asked Claude to build a view or implement a form, it was back and forth. “Use the card partial, not a div.” “The input needs a data attribute.” “That’s not how the combobox works.” I spent as much time correcting the AI as I would have spent writing the code myself.</p> <p>The same friction appeared when writing specs. I’d describe a feature and Claude would suggest generic Rails patterns instead of the components I had available. It didn’t know about the library. How could it?</p> <h2 id="the-skill-experiment">The Skill Experiment</h2> <p>When Anthropic released the <a href="https://docs.anthropic.com/en/docs/claude-code/skills">Skills functionality</a>, I wondered if it was the right tool for this problem. Skills let you teach Claude project-specific knowledge—conventions, patterns, APIs. Exactly what was missing.</p> <p>I created a first version: a structured reference with component examples, form patterns, layout conventions, and Turbo integration guides. Added it to my projects and started using it.</p> <p>It worked. Claude started generating code that matched my conventions. The combobox had proper keyboard navigation. Forms used the right data attributes. Turbo Streams updated components correctly. The back-and-forth dropped significantly.</p> <p>I kept the skill private. It was tied to my workflow, my projects. Not ready for others.</p> <h2 id="making-it-public">Making It Public</h2> <p>Yesterday I published <a href="/blog/maquina-components-0-3-0/">Maquina Components 0.3.0</a> with Combobox and Toast. Shortly after, someone asked if I had an MCP server for the components.</p> <p>I replied that I had something better—a Claude Skill that I’d been using for while now. It was working great with the gem.</p> <p>So I decided to open source it.</p> <h2 id="what-the-skill-provides">What the Skill Provides</h2> <p>A complete reference for building UIs with maquina_components:</p> <table> <thead> <tr> <th>Reference</th> <th>Purpose</th> </tr> </thead> <tbody> <tr> <td>Component catalog</td> <td>All 15+ components with ERB examples</td> </tr> <tr> <td>Form patterns</td> <td>Validation, error handling, inline layouts</td> </tr> <tr> <td>Layout patterns</td> <td>Sidebar navigation, page structure</td> </tr> <tr> <td>Turbo integration</td> <td>Frames, Streams, component updates</td> </tr> <tr> <td>Spec checklist</td> <td>Review criteria for UI quality</td> </tr> </tbody> </table> <h2 id="installation">Installation</h2> <p>Create a skills directory in your Rails project:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cd </span>your-rails-app <span class="nb">mkdir</span> <span class="nt">-p</span> .claude/skills </code></pre></div></div> <p>Download the skill from the <a href="https://github.com/maquina-app/maquina_components/tree/main/skill">maquina_components repository</a> and copy it to <code class="highlighter-rouge">.claude/skills/maquina-ui-standards/</code>.</p> <p>Then update your <code class="highlighter-rouge">CLAUDE.md</code> to reference it:</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gu">## UI Components</span> This project uses maquina_components for UI. Before implementing views, forms, or interactive components, read the UI standards skill: .claude/skills/maquina-ui-standards/SKILL.md Always consult the skill when: <span class="p">-</span> Creating or modifying views <span class="p">-</span> Implementing forms <span class="p">-</span> Adding interactive components <span class="p">-</span> Building layouts with sidebar/header patterns <span class="p">-</span> Working with Turbo Streams that update UI </code></pre></div></div> <h2 id="usage">Usage</h2> <p>Once installed, ask Claude naturally:</p> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Create the users index view with a table showing name, email, and status. </code></pre></div></div> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Implement the project form with name, description, and a framework combobox. </code></pre></div></div> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Review this view against the maquina UI standards and suggest improvements. </code></pre></div></div> <p>The generated code matches what you’d write manually—just faster, and without the back-and-forth.</p> <h2 id="source">Source</h2> <p>The skill is included in the <a href="https://github.com/maquina-app/maquina_components/tree/main/skill">maquina_components repository</a> under MIT license. Updates follow gem releases.</p>Mario Alberto Chávez Cárdenas2026-01-07T00:00:00-06:002026-01-07T00:00:00-06:00repo://posts.collection/_posts/2026-01-07-maquina-components-0-3-0.md<p>Version 0.3.0 of <a href="/blog/2025/12/announcing-maquina-components-opinionated-ul-for-rails-applications/">Maquina Components</a> adds two frequently requested interactive components: <strong>Combobox</strong> and <strong>Toast</strong>.</p> <p>Both components follow the same philosophy as the rest of the library—ERB partials, Tailwind CSS, and Stimulus controllers only where necessary.</p> <h2 id="combobox">Combobox</h2> <p><img alt="Combobox" src="/images/components/combobox.png" class="mb-10 w-full rounded-2xl object-cover" /></p> <p>An autocomplete input with a searchable dropdown list. Useful when selecting from many options—countries, users, tags, or any list that benefits from filtering.</p> <div class="language-erb highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;%=</span> <span class="n">combobox</span> <span class="ss">placeholder: </span><span class="s2">"Select framework..."</span> <span class="k">do</span> <span class="o">|</span><span class="n">cb</span><span class="o">|</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="n">cb</span><span class="p">.</span><span class="nf">trigger</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="n">cb</span><span class="p">.</span><span class="nf">content</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="n">cb</span><span class="p">.</span><span class="nf">input</span> <span class="ss">placeholder: </span><span class="s2">"Search..."</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="n">cb</span><span class="p">.</span><span class="nf">list</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="n">cb</span><span class="p">.</span><span class="nf">option</span> <span class="ss">value: </span><span class="s2">"rails"</span> <span class="k">do</span> <span class="cp">%&gt;</span>Ruby on Rails<span class="cp">&lt;%</span> <span class="k">end</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="n">cb</span><span class="p">.</span><span class="nf">option</span> <span class="ss">value: </span><span class="s2">"django"</span> <span class="k">do</span> <span class="cp">%&gt;</span>Django<span class="cp">&lt;%</span> <span class="k">end</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%</span> <span class="n">cb</span><span class="p">.</span><span class="nf">option</span> <span class="ss">value: </span><span class="s2">"phoenix"</span> <span class="k">do</span> <span class="cp">%&gt;</span>Phoenix<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="n">cb</span><span class="p">.</span><span class="nf">empty</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>For simpler use cases, the data-driven helper builds the entire structure from an array:</p> <div class="language-erb highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;%=</span> <span class="n">combobox_simple</span> <span class="ss">placeholder: </span><span class="s2">"Select country..."</span><span class="p">,</span> <span class="ss">name: </span><span class="s2">"user[country]"</span><span class="p">,</span> <span class="ss">options: </span><span class="no">Country</span><span class="p">.</span><span class="nf">all</span><span class="p">.</span><span class="nf">map</span> <span class="p">{</span> <span class="o">|</span><span class="n">c</span><span class="o">|</span> <span class="p">{</span> <span class="ss">value: </span><span class="n">c</span><span class="p">.</span><span class="nf">code</span><span class="p">,</span> <span class="ss">label: </span><span class="n">c</span><span class="p">.</span><span class="nf">name</span> <span class="p">}</span> <span class="p">}</span> <span class="cp">%&gt;</span> </code></pre></div></div> <h3 id="features">Features</h3> <ul> <li>Keyboard navigation (arrows, Home, End, Escape)</li> <li>Real-time filtering as you type</li> <li>Grouped options with labels and separators</li> <li>Multiple width and alignment options</li> <li>Full ARIA support (<code class="highlighter-rouge">role="combobox"</code>, <code class="highlighter-rouge">role="listbox"</code>)</li> </ul> <h3 id="requirements">Requirements</h3> <p>The Combobox uses the HTML5 Popover API for light-dismiss behavior. Most modern browsers support it natively:</p> <table> <thead> <tr> <th>Browser</th> <th>Version</th> </tr> </thead> <tbody> <tr> <td>Chrome</td> <td>114+</td> </tr> <tr> <td>Edge</td> <td>114+</td> </tr> <tr> <td>Safari</td> <td>17+</td> </tr> <tr> <td>Firefox</td> <td>125+</td> </tr> </tbody> </table> <p>For older browsers, add the <a href="https://github.com/oddbird/popover-polyfill">popover polyfill</a>:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>npm <span class="nb">install</span> @oddbird/popover-polyfill </code></pre></div></div> <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// app/javascript/application.js</span> <span class="k">import</span> <span class="dl">"</span><span class="s2">@oddbird/popover-polyfill</span><span class="dl">"</span> </code></pre></div></div> <h2 id="toast">Toast</h2> <p><img alt="Combobox" src="/images/components/toast.png" class="mb-10 w-full rounded-2xl object-cover" /></p> <p>Non-intrusive notifications that appear temporarily and dismiss automatically. Ideal for form submission feedback, background task completion, or any transient message.</p> <h3 id="server-side-with-flash-messages">Server-Side with Flash Messages</h3> <p>The most common pattern—render Rails flash messages as toasts:</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/toaster"</span><span class="p">,</span> <span class="ss">position: :bottom_right</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%=</span> <span class="n">toast_flash_messages</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> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># In your controller</span> <span class="n">flash</span><span class="p">[</span><span class="ss">:success</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"Profile updated successfully!"</span> <span class="n">redirect_to</span> <span class="vi">@user</span> </code></pre></div></div> <p>Flash types map automatically to toast variants: <code class="highlighter-rouge">:success</code>, <code class="highlighter-rouge">:error</code>, <code class="highlighter-rouge">:warning</code>, <code class="highlighter-rouge">:info</code>.</p> <h3 id="javascript-api">JavaScript API</h3> <p>For dynamic notifications without a page reload:</p> <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">Toast</span><span class="p">.</span><span class="nf">success</span><span class="p">(</span><span class="dl">"</span><span class="s2">Changes saved!</span><span class="dl">"</span><span class="p">)</span> <span class="nx">Toast</span><span class="p">.</span><span class="nf">error</span><span class="p">(</span><span class="dl">"</span><span class="s2">Connection lost</span><span class="dl">"</span><span class="p">,</span> <span class="p">{</span> <span class="na">description</span><span class="p">:</span> <span class="dl">"</span><span class="s2">Please check your internet connection.</span><span class="dl">"</span> <span class="p">})</span> <span class="nx">Toast</span><span class="p">.</span><span class="nf">warning</span><span class="p">(</span><span class="dl">"</span><span class="s2">Session expiring</span><span class="dl">"</span><span class="p">,</span> <span class="p">{</span> <span class="na">duration</span><span class="p">:</span> <span class="mi">10000</span> <span class="p">})</span> <span class="c1">// Dismiss programmatically</span> <span class="kd">const</span> <span class="nx">id</span> <span class="o">=</span> <span class="nx">Toast</span><span class="p">.</span><span class="nf">info</span><span class="p">(</span><span class="dl">"</span><span class="s2">Processing...</span><span class="dl">"</span><span class="p">)</span> <span class="nx">Toast</span><span class="p">.</span><span class="nf">dismiss</span><span class="p">(</span><span class="nx">id</span><span class="p">)</span> </code></pre></div></div> <h3 id="with-turbo-streams">With Turbo Streams</h3> <p>Append toasts to the container in Turbo Stream responses:</p> <div class="language-erb highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;%=</span> <span class="n">turbo_stream</span><span class="p">.</span><span class="nf">append</span> <span class="s2">"toaster"</span> <span class="k">do</span> <span class="cp">%&gt;</span> <span class="cp">&lt;%=</span> <span class="n">toast</span> <span class="ss">:success</span><span class="p">,</span> <span class="s2">"Post published!"</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> <h3 id="features-1">Features</h3> <ul> <li>Five variants: default, success, info, warning, error</li> <li>Auto-dismiss with configurable duration (pauses on hover)</li> <li>Six positioning options (corners and center edges)</li> <li>Optional action buttons for undo/view operations</li> <li>Full keyboard accessibility</li> </ul> <h3 id="requirements-1">Requirements</h3> <p>Toast requires Stimulus for the auto-dismiss timer and JavaScript API. Add the controller to your Stimulus application:</p> <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// app/javascript/application.js</span> <span class="k">import</span> <span class="p">{</span> <span class="nx">Application</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">"</span><span class="s2">@hotwired/stimulus</span><span class="dl">"</span> <span class="k">import</span> <span class="p">{</span> <span class="nx">eagerLoadControllersFrom</span> <span class="p">}</span> <span class="k">from</span> <span class="dl">"</span><span class="s2">@hotwired/stimulus-loading</span><span class="dl">"</span> <span class="kd">const</span> <span class="nx">application</span> <span class="o">=</span> <span class="nx">Application</span><span class="p">.</span><span class="nf">start</span><span class="p">()</span> <span class="nf">eagerLoadControllersFrom</span><span class="p">(</span><span class="dl">"</span><span class="s2">controllers</span><span class="dl">"</span><span class="p">,</span> <span class="nx">application</span><span class="p">)</span> </code></pre></div></div> <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>No generator changes are required. Both components use the existing theme variables.</p> <h2 id="see-them-in-action">See Them in Action</h2> <p>To explore Combobox, Toast, and all other components with demo data, clone the repository and run the dummy application:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone https://github.com/maquina-app/maquina_components.git <span class="nb">cd </span>maquina_components/test/dummy bin/dev </code></pre></div></div> <p>Then visit <a href="http://localhost:5300">http://localhost:5300</a> to interact with the full component showcase.</p> <h2 id="documentation">Documentation</h2> <ul> <li><a href="/documentation/components/combobox/">Combobox documentation</a></li> <li><a href="/documentation/components/toast/">Toast documentation</a></li> <li><a href="/documentation/components/">Full component list</a></li> </ul> <h2 id="source">Source</h2> <p>The gem is MIT licensed. Source and issues on <a href="https://github.com/maquina-app/maquina_components">GitHub</a>.</p>Mario Alberto Chávez Cárdenas2025-12-29T00:00:00-06:002025-12-29T00:00:00-06:00repo://posts.collection/_posts/2025-12-29-rails-mcp-1-5.md<p>Open source projects get better when people contribute back. Rails MCP Server 1.5.0 is a direct result of that—a release shaped significantly by a community contribution that I didn’t write.</p> <p>The most important change in this version is a comprehensive security overhaul contributed by GitHub user <a href="https://github.com/hellvinz">hellvinz</a> through <a href="https://github.com/maquina-app/rails-mcp-server/pull/25">PR #25</a>. It’s the kind of work that doesn’t get enough recognition.</p> <h2 id="the-security-contribution">The Security Contribution</h2> <p>When you give an AI model access to your codebase through MCP tools, security matters. The <code class="highlighter-rouge">execute_ruby</code> sandbox already restricted dangerous operations, but the file-accessing analyzers needed more rigorous input validation.</p> <p><strong>PathValidator Module</strong></p> <p>A centralized validation layer now protects all file-accessing analyzers. Path traversal attempts are blocked. Sensitive files are filtered automatically. The implementation is clean:</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Path traversal attempts are blocked</span> <span class="n">get_file</span><span class="p">(</span><span class="ss">path: </span><span class="s2">"../../../etc/passwd"</span><span class="p">)</span> <span class="c1"># =&gt; "Access denied: Path is outside the project directory"</span> <span class="c1"># Sensitive files are filtered</span> <span class="n">list_files</span><span class="p">(</span><span class="ss">pattern: </span><span class="s2">"config/*.key"</span><span class="p">)</span> <span class="c1"># =&gt; master.key, credentials.yml.enc excluded from results</span> </code></pre></div></div> <p>The validator catches:</p> <ul> <li>Path traversal attacks (<code class="highlighter-rouge">../</code> sequences)</li> <li>Absolute path access outside the project</li> <li>Attempts to read sensitive files (master.key, credentials.yml.enc, .env)</li> </ul> <p><strong>Injection Prevention</strong></p> <p>Shell commands now use <code class="highlighter-rouge">IO.popen</code> with array arguments instead of string interpolation. Table names in schema queries are validated against a strict pattern. These changes close potential injection vectors that existed in earlier versions.</p> <p><strong>CI Infrastructure</strong></p> <p>Beyond the code changes, hellvinz added security infrastructure I should have set up from the start:</p> <ul> <li>Dependabot for dependency updates</li> <li>CodeQL for static analysis</li> <li>OpenSSF Scorecard integration</li> <li>A proper SECURITY.md for vulnerability reporting</li> </ul> <p>This kind of contribution takes real effort. Reviewing an unfamiliar codebase, identifying gaps, implementing fixes that don’t break existing functionality, unglamorous work that makes the project better for everyone who uses it.</p> <p>I’m grateful for the contribution.</p> <h2 id="sandboxed-environment-support">Sandboxed Environment Support</h2> <p>AI coding agents increasingly run in sandboxed environments—containers or restricted shells where they can only access the current project directory. GitHub Copilot Agent and Claude Code Agent both work this way.</p> <p>Previous versions of Rails MCP Server assumed access to a user home directory for configuration files. That doesn’t work in a sandbox.</p> <p>The <code class="highlighter-rouge">--single-project</code> flag solves this. It tells the server to use the current working directory as the only project, skipping configuration files entirely:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>rails-mcp-server <span class="nt">--single-project</span> </code></pre></div></div> <p><strong>GitHub Copilot Agent</strong> configuration goes in <code class="highlighter-rouge">.vscode/mcp.json</code>:</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">"servers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"rails-mcp"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"command"</span><span class="p">:</span><span class="w"> </span><span class="s2">"rails-mcp-server"</span><span class="p">,</span><span class="w"> </span><span class="nl">"args"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"--single-project"</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><strong>Claude Code Agent</strong> can use the same flag. The server detects it’s running in a Rails directory and works immediately—no setup required.</p> <p>This also simplifies CI/CD pipelines and any environment where you want the server to just work with the current directory.</p> <p>The <a href="https://github.com/maquina-app/rails-mcp-server/blob/main/docs/COPILOT_AGENT.md">Copilot Agent documentation</a> covers the setup in detail.</p> <h2 id="simplified-project-configuration">Simplified Project Configuration</h2> <p>Previous versions required manual configuration in <code class="highlighter-rouge">~/.config/rails-mcp/projects.yml</code>. That still works, but 1.5.0 adds flexibility:</p> <table> <thead> <tr> <th>Method</th> <th>Use Case</th> </tr> </thead> <tbody> <tr> <td><code class="highlighter-rouge">--single-project</code> flag</td> <td>Sandboxed agents (Copilot, Claude Code), CI/CD</td> </tr> <tr> <td><code class="highlighter-rouge">RAILS_MCP_PROJECT_PATH</code> env var</td> <td>Explicit path control</td> </tr> <tr> <td>Auto-detection</td> <td>Finds Rails apps from Gemfile, engines from gemspec</td> </tr> <tr> <td><code class="highlighter-rouge">projects.yml</code></td> <td>Multiple projects with named references</td> </tr> </tbody> </table> <p>The server now auto-detects Rails applications by checking for a Gemfile with the <code class="highlighter-rouge">rails</code> gem, and Rails engines by looking for gemspec files with Rails dependencies. When only one project is available, it switches automatically.</p> <h2 id="rails-81-compatibility">Rails 8.1 Compatibility</h2> <p>Rails 8.1 changed the internal callback API. The <code class="highlighter-rouge">analyze_controller_views</code> tool was calling <code class="highlighter-rouge">callback.options</code> to extract <code class="highlighter-rouge">:only</code> and <code class="highlighter-rouge">:except</code> conditions, but that method no longer exists.</p> <p>The fix maintains backward compatibility:</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="ss">callbacks: </span><span class="n">controller</span><span class="p">.</span><span class="nf">_process_action_callbacks</span><span class="p">.</span><span class="nf">map</span> <span class="p">{</span> <span class="o">|</span><span class="n">cb</span><span class="o">|</span> <span class="n">h</span> <span class="o">=</span> <span class="p">{</span> <span class="ss">kind: </span><span class="n">cb</span><span class="p">.</span><span class="nf">kind</span><span class="p">.</span><span class="nf">to_s</span><span class="p">,</span> <span class="ss">filter: </span><span class="n">cb</span><span class="p">.</span><span class="nf">filter</span><span class="p">.</span><span class="nf">to_s</span> <span class="p">}</span> <span class="k">if</span> <span class="n">cb</span><span class="p">.</span><span class="nf">respond_to?</span><span class="p">(</span><span class="ss">:options</span><span class="p">)</span> <span class="n">h</span><span class="p">[</span><span class="ss">:only</span><span class="p">]</span> <span class="o">=</span> <span class="no">Array</span><span class="p">(</span><span class="n">cb</span><span class="p">.</span><span class="nf">options</span><span class="p">[</span><span class="ss">:only</span><span class="p">]).</span><span class="nf">map</span><span class="p">(</span><span class="o">&amp;</span><span class="ss">:to_s</span><span class="p">)</span> <span class="n">h</span><span class="p">[</span><span class="ss">:except</span><span class="p">]</span> <span class="o">=</span> <span class="no">Array</span><span class="p">(</span><span class="n">cb</span><span class="p">.</span><span class="nf">options</span><span class="p">[</span><span class="ss">:except</span><span class="p">]).</span><span class="nf">map</span><span class="p">(</span><span class="o">&amp;</span><span class="ss">:to_s</span><span class="p">)</span> <span class="k">end</span> <span class="n">h</span> <span class="p">}</span> </code></pre></div></div> <p>This works with Rails 6.0 through 8.1. The callback conditions are extracted when available, omitted when not.</p> <h2 id="other-changes">Other Changes</h2> <p><strong>Error messages</strong> now include hints. When you ask for a model named <code class="highlighter-rouge">users</code> instead of <code class="highlighter-rouge">User</code>, the error explains the naming convention. Small things that reduce friction.</p> <p><strong>Parameter passing</strong> in <code class="highlighter-rouge">execute_tool</code> is fixed. The params schema now generates correctly for MCP clients, so tools like <code class="highlighter-rouge">analyze_models</code> can actually receive their parameters. This was a real bug that made the tool harder to use than it should have been.</p> <p><strong>Input validation</strong> for <code class="highlighter-rouge">load_guide</code> prevents path traversal in guide names. Another gap that hellvinz’s security review prompted me to address.</p> <h2 id="breaking-change">Breaking Change</h2> <p>The <code class="highlighter-rouge">load_guide</code> analyzer renamed its parameter from <code class="highlighter-rouge">guides</code> to <code class="highlighter-rouge">library</code>:</p> <div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Before (1.4.x)</span> <span class="n">execute_tool</span><span class="p">(</span><span class="s2">"load_guide"</span><span class="p">,</span> <span class="p">{</span> <span class="ss">guides: </span><span class="s2">"rails"</span><span class="p">,</span> <span class="ss">guide: </span><span class="s2">"active_record"</span> <span class="p">})</span> <span class="c1"># After (1.5.0)</span> <span class="n">execute_tool</span><span class="p">(</span><span class="s2">"load_guide"</span><span class="p">,</span> <span class="p">{</span> <span class="ss">library: </span><span class="s2">"rails"</span><span class="p">,</span> <span class="ss">guide: </span><span class="s2">"active_record"</span> <span class="p">})</span> </code></pre></div></div> <p>The change clarifies that you’re selecting a documentation library (rails, turbo, stimulus, kamal, custom), not multiple guides. It’s a small breaking change, but the naming is more accurate.</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’re using Claude Desktop, restart it to pick up the new version. The server 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> <p>The interactive configuration tool handles Claude Desktop setup, project registration, and guide downloads.</p> <h2 id="whats-next">What’s Next</h2> <p>The MCP specification continues to evolve. As more AI tools adopt the protocol, Rails MCP Server will adapt to support them.</p> <p>If you find issues or have ideas, the <a href="https://github.com/maquina-app/rails-mcp-server/issues">issue tracker</a> is open. Pull requests are welcome. As this release shows, community contributions make a real difference—sometimes more than you might expect.</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/docs/AGENT.md">AI Agent Guide</a></li> <li><a href="https://github.com/maquina-app/rails-mcp-server/blob/main/docs/COPILOT_AGENT.md">Copilot Agent Setup</a></li> </ul>Mario Alberto Chávez Cárdenas