Add agentation-rails gem

[stevysmith]

Summary

Adds agentation-rails — a Rails engine gem that brings the Agentation toolbar to Rails apps. One line in the Gemfile, zero configuration.

# Gemfile
gem "agentation-rails", group: :development

The gem auto-injects the toolbar into every HTML response in development via Rack middleware — the same pattern used by bullet, web-console, and rack-mini-profiler. Rails devs never touch React or modify their views.

What's included

• Rack middleware that injects a <script> tag (toolbar IIFE) and a config <div> into HTML responses
• Pre-built JS artifact via pnpm build:rails — bundles React + Agentation into a single self-executing script so Rails devs never see React
• CustomEvent bridge — all annotation lifecycle events (agentation:add, :delete, :update, :clear, :copy, :submit, :session) dispatched on document for use with Stimulus or plain JS
• rails generate agentation:install generator for optional config
• Turbo/Turbolinks support — unmounts before cache, re-mounts on navigation
• Safety: XSS-escapes all injected data attributes, skips streaming responses, Cache-Control: no-store on the JS asset

How it connects to Agents

A Rails user's full setup is:

1. gem "agentation-rails", group: :development + bundle install (toolbar appears)
2. npx skills add benjitaylor/agentation (installs the /agentation Agent skill)
3. Add agentation-mcp to ~/.claude/claude_code_config.json (so agent receives annotations)

The gem replaces both npm install agentation and adding <Agentation /> to the component tree — the middleware handles injection automatically, which is the standard Rails convention for dev tooling.

Maintenance notes

Rebuilding the JS when the npm package changes

The gem ships a pre-built IIFE at rails/gem/app/assets/javascripts/agentation.js. After any change to the main agentation package, rebuild it:

pnpm build:rails

The build reads the version from package/package.json and injects it as __VERSION__, so the npm version is the source of truth. If you ship a new npm version without running pnpm build:rails, the gem will serve stale JS.

Version bumping on release

Two places need manual updates:

What	File
npm package (source of truth)	package/package.json
Rails gem	rails/gem/agentation-rails.gemspec

Publishing to RubyGems

The gem isn't published yet. When ready:

cd rails/gem
gem build agentation-rails.gemspec
gem push agentation-rails-2.1.1.gem

For easier maintenance consider adding a publish:rails script to the root package.json alongside the existing publish:agentation and publish:mcp.

Demo of Setup & Use in Rails

agentation-rails.mp4

Why Rails?

whyrails.mp4

Why this method?

Keeps the npm package as the source of truth and reduces maintenance complexity - just adds a build step. This follows the same approach as the following libraries:

• turbo-rails — wraps @hotwired/turbo (npm package) into a gem, vendors the compiled JS
• stimulus-rails — wraps @hotwired/stimulus the same way
• tailwindcss-rails — bundles the Tailwind standalone binary so there's zero Node dependency
• chartkick — exists as both an npm package and a gem, the gem bundles the JS
• rack-mini-profiler — has its own JS/CSS UI compiled and vendored inside the gem
• blazer — Shopify's analytics engine, bundles its full JS frontend into the gem

[vercel]

@stevysmith is attempting to deploy a commit to the Benji Taylor's Projects Team on Vercel.

A member of the Team first needs to authorize it.