Implementation Cookbook
Canonical, copy-pasteable guides for the patterns we've built and proven — UI/UX components, controller actions, models, SQL, and Stimulus controllers. Built to be recreated by you or any coding agent.
Navbar User Chip with Role & Sign-Out
Top-right user identity chip — avatar photo or initials, the user's name with their role beneath it, and a sign-out arrow — packaged as one shared partial.
One-Click Demo Sign-In Button (Devise)
A "Sign into Demo" button on the Devise sign-in page that logs a visitor into a shared demo account with one click — a hidden pre-filled sign-in form, no routes or controller changes.
Rate Limiting, IP Allowlists & a Request Audit Trail
Rack::Attack throttles for login brute-force and request floods, a trusted-IP safelist, an optional country allowlist, and a UserEvent audit log that records who did what from which IP. Includes the two silent failures that make throttling do nothing at all.
Sign in with your LlamaPress.ai Account (SSO)
Put the "Sign in with your LlamaPress.ai account" button on your Devise sign-in page so the box owner signs in with their llamapress.ai identity instead of a password — one view line, plus the user-provisioning step the gem does not do for you.
Two-Factor Authentication (TOTP) with Remember-This-Device
A two-step TOTP second factor on top of Devise — QR enrollment, a per-login code challenge, a 14-day signed "remember this device" cookie, and an admin lost-device reset. Uses devise-two-factor + rqrcode, both already in the base image.
User Impersonation ("Sign in as this user")
Let an admin log in as another user to debug or support them, with a persistent "you are impersonating" banner and one-click return to the admin account.
Team Directory with Per-Member Task Backlog
A /team directory of member cards, each linking to a per-member task backlog — Backlog/Completed tabs, priority sort, an inline add form, one-click completion tickboxes, and drag-and-drop reordering persisted via SortableJS + one Stimulus controller.
Choosing the Right Chart
A question-first chart chooser plus the no-library ERB/CSS/SVG recipes — why sorted bars beat pies, when a big number beats any chart, the perceptual ranking behind it, and working partials for a sorted bar chart, a fixed-scale heatmap, and a waterfall.
Color, Icons, and Contrast
How to spend color and icons so a screen tells the eye where to look — grey by default, one meaning per color, status color in text/badges vs entity color in chart marks, never color alone, and the WCAG contrast floors including the 3:1 rule for chart bars.
Progressive Disclosure for Dense Detail Pages
A layout method for record pages that have too much to show — name the one job, cap the glance layer at five elements, put everything else behind tabs and collapsed rows, and spend colour only on "a human must act".
Generate PDFs (headless Chrome) without wedging your app
A naive `grover.to_pdf` in a controller can freeze your entire app (blank screen / infinite spinner). Funnel every PDF render through one safe helper — single-flight, hard timeout, self-contained HTML — so a slow or hung render can never take the app down.
PDF & Image Preview Modal for Uploaded Files
Click an uploaded document row to preview the PDF (or image) full-screen in a native <dialog> modal, with a download button — no page reload, no PDF library, no extra gems.
Async Actions Need Feedback (no dead buttons)
Any button that triggers non-instant work must show immediate in-flight feedback — disable + spinner, optimistic UI, and a clear result (and failure) toast.
Free-Tier Address Search & Map Selection
Add Google-Maps-style address autocomplete and a draggable map pin using Intterra's proven Mapbox Search + Leaflet/CARTO pattern, with no paid mapping SDK or new gem.
Password Show/Hide Toggle (eye icon or checkbox)
Two ways to let users reveal a password before submitting — a clickable eye icon inside the field, or an explicit "Show password" checkbox below it — sharing one tiny Stimulus controller.
Search-and-Add Tagger (find a record or create it, in one field)
One input that searches an existing table, shows matches as you type, lets you create a brand-new record inline when there is no match, and renders picks as removable badges — works both inside a new-record form and as an auto-saving sidebar widget.
'Ask Leo to..' Buttons (prefill Leo's chat from your app)
Buttons on your app's pages that drop a pre-written command straight into Leo's chat input via postMessage — one click instead of the user typing the request out.
Apple Calendar (iCloud) Two-Way Sync via CalDAV
Show a shared Apple/iCloud calendar inside your app and write events back onto it — no gems, no OAuth app, just Net::HTTP speaking CalDAV with an app-specific password.
Custom Leo Agent Mode — Own Prompt, Own Tools, Authenticated Rails API
Add a custom agent to the Leo chat mode dropdown — its own LangGraph graph, system prompt, model, a tool that calls your Rails API as the signed-in user, plus current-page context and live browser control. Three mounted files, no image rebuild.
Google Ads API — OAuth, REST Client & Keyword Research
Complete Google Ads API integration with zero gems — org-level OAuth connect flow storing only a refresh token, a plain Net::HTTP REST client (the official gem sunsets too fast to bake), GAQL reporting, Keyword Planner research (ideas + historical volumes), the no-API CSV fallback, and a template for saving the working setup as a local agent skill.
Google Calendar Integration — Per-User OAuth & Meeting Sync
Let each signed-in user connect their own Google Calendar with OAuth (offline access + refresh tokens), sync their upcoming events into a local table with a zero-gem Net::HTTP background job, extract the Meet/Zoom/Teams join link, and render an "Upcoming meetings" widget — including token refresh, revoked-token recovery, and keeping moved meetings up to date.
Google Search Console — OAuth Client, Callback URI & Pulling Query Data
Wire Google Search Console into a Rails app with zero gems — create the Google Cloud OAuth client ID (Web application type), set the Authorized redirect URI callback, store credentials in .env, mint a durable refresh token (in-app flow or OAuth Playground), and pull real search-query data (impressions, clicks, CTR, position) with a plain Net::HTTP client.
Install Agent Gmail Service
Give your app a Gmail mailbox the agent can read and write — per-user OAuth, encrypted refresh tokens, a GmailAgent service (search/read/label/send), and a draft-first AgentGmailTools wrapper that will not mail a customer without an explicit confirm. Includes the reply-threading fix that stops your replies arriving as brand-new conversations.
Install Leo SMS Gateway
A two-way SMS/MMS gateway your app owns — inbound Twilio webhook to database rows, a threaded inbox UI, outbound send with delivery receipts, group texts — plus the Codex CLI /goal loop that checks the text inbox (and Gmail) every 10 minutes, sleeps itself between ticks, and asks a human before answering anyone.
OpenWiki: Repo Docs, Admin Browser, Nightly Cron, and a PaperTrail Feed
Run OpenWiki so an AI agent keeps a living wiki of your repo, browse it inside your admin at /admin/open-wiki, schedule it with a hardened nightly cron, and extend it past code by feeding it a PaperTrail data-change digest.
Outbound Email Safelist — Send Every Test Email to the Developer, Not Real People
An Action Mailer interceptor that auto-redirects every outbound email to one or more developer inboxes while the app is still being built, and appends a "this would have gone to <customer>" notice to the body so nobody is confused. Covers the reroute-don't-drop rule, multipart body rewriting, both registration methods, the EMAIL_SAFELIST env switch, and how to remove it on go-live.
Plaid — Bank Account Linking & Transaction Sync
Full Plaid integration with zero gems — plain Net::HTTP service module, Plaid Link frontend, cursor-based transactions/sync job, webhook-driven updates, a connection-health state machine for re-auth, and the hard-won fixes for the "two accounts at the same bank" data-crossing trap.
Recall.ai Meeting Bot — Transcript, Captions & Recording
Send an AI notetaker bot into a Zoom/Meet/Teams call — with a branded camera tile — then pull back the transcript, WebVTT captions, and the video recording, wired to a record in your app.
Twilio — SMS Sending & Phone Verification
Drop-in Twilio module for sending SMS texts and verifying phone numbers (Twilio Verify), the API-key-first credential setup (TWILIO_SID/TWILIO_AUTH/TWILIO_ACCOUNT_SID/TWILIO_NUMBER), and the container-recreate step that actually loads them. The twilio-ruby gem is already in the base image.
Unsplash API — Stock Photos with Attribution
Drop-in UnsplashService (plain Net::HTTP, no gem) to search and fetch stock photos, the .env keys it needs, and the mandatory photographer/Unsplash attribution pattern for views.
ImageMagick Image Cropping & Transparency
Trim whitespace, make backgrounds transparent, recolor a logo white for dark headers, and build centered/padded variants with ImageMagick — then swap the result into a Rails view.
Textured Section Backgrounds (Pure CSS)
18 modern texture and pattern recipes for section backgrounds — dots, grids, noise grain, mesh gradients, spotlight beams, animated auroras — all pure CSS or inline SVG, zero image files.
Cmd+K Global Search (search across many tables at once)
A Cmd+K / click-the-magnifying-glass command palette that opens a modal, queries several tables at once, and streams grouped, clickable results back via Turbo.
Publish to Your Personal Cookbook
How a Leo instance saves a reusable recipe to its owner's public cookbook at llamapress.ai/cookbook/u/<handle>, so every one of their Leos can reuse it.
Filterable Index with Slide-Out Detail Drawer
A Retool-style admin index — a condensed table showing only key columns, a collapsible left-hand filter/search panel, and a right-hand slide-out drawer that loads the full show/edit views for a row via one Turbo Frame, no page reloads.
Focus Jumping in Inline-Editable Tables
Why focus flies to the first row of the table after an inline edit saves, and the snapshot-restore-verify pattern that puts the cursor back where the user left it when Turbo replaces the whole row.
High-Quality Inline-Editable Table
A spreadsheet-grade data table — click-to-edit cells, Tab/Enter navigation, debounced autosave with a saving/saved indicator, sortable columns, and debounced server-side search.
Multi-Select, Bulk Edit & Mass Reassignment
Multi-select rows and apply one change to all of them — with an explicit field list, a real "leave this alone" state, mixed-value display, a blast-radius preview, a batch record you can undo, and a guard that refuses to blank real data.
No guides match your search.