rails-hyperdrive 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7577ebf92af02fb8bb079a8b32c8751744340390f0f0facc0e682bc31aa6d43d
+  data.tar.gz: 990f940533691baf570a17113806fcd274300b56ee171a22195921ea9ddeb6bd
+SHA512:
+  metadata.gz: af48e37db907f10bf2a74d8303aa57b5cd04bd44d7ab97834bc197d97f39cf77cef87116217ce8d773d95d5ae6d93b6e216cbec275b3886bdb7c9b32cbe356af
+  data.tar.gz: 99144761cd64cf3bbed57caf0eaa0ab691511d7246e7add30e8fdf94bcd2f1e857c0b1612b5b95033a9336ca71faf80bd9bdae3db9813c3377dea3efdf6986c7

data/CHANGELOG.md

@@ -0,0 +1,295 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-04
+
+### Added
+
+- `bundler-rails-hyperdrive`, a Bundler plugin gem co-located in this repository
+  (`bundler-rails-hyperdrive/`). Once registered, it runs after every
+  `bundle install` in development and installs the artifacts that newly
+  bundled companion gems ship — additive only (it never overwrites or
+  deletes a file) — and reports upgraded or orphaned artifacts with a
+  pointer to `bin/rails hyperdrive:sync`. It resolves rails-hyperdrive from
+  the application's bundle at runtime (supported range `>= 0.2`), stays
+  silent outside development, and never fails a `bundle install`.
+- `hyperdrive:init` now registers the plugin by appending
+  `plugin "bundler-rails-hyperdrive"` to the application's Gemfile. Idempotent: an
+  existing directive (with any options) is left alone, and an app without a
+  Gemfile gets a skip status.
+- **Gem-conditional skill content.** A multi-file skill can now condition parts
+  of itself on the app's bundle, through two complementary mechanisms evaluated
+  at discovery time:
+  - A `conditional:` map in `SKILL.md` frontmatter gates individual supporting
+    files per gem. Keys are dir-relative shipped paths; values reuse the
+    artifact-level `gem:`/`versions:` forms (single target, comma-separated
+    string, YAML list, per-target `versions:` map, `"*"`), with `versions:`
+    optional (omitted = unconstrained). A gated file installs only when a
+    listed target is bundled at a satisfying version, and disappears on the
+    next `hyperdrive:sync` when its gate closes (unedited copies only). A
+    malformed condition fails open — the file installs and the problem is
+    reported as a discovery warning.
+  - Files named `*.md.erb` in a skill directory — including `SKILL.md.erb` in
+    place of `SKILL.md` — are rendered at install time with a sealed helper
+    binding (`gem?`, `any_gem?`, `gem_version`) over the resolved bundle, and
+    install as plain `.md`. A template that fails to render is skipped with a
+    warning (the whole skill, for `SKILL.md.erb`); a plain file always beats a
+    template rendering to the same path.
+
+- **Multi-file skills.** A companion skill directory can now ship more than
+  `SKILL.md`: every other file in it (nested however deep — `workflows/`,
+  `references/`, `examples/`, …) installs as a **supporting file** under
+  `.claude/skills/<name>/`, preserving the relative layout, so `SKILL.md` can
+  reference it with directory-relative links (which survive cross-source
+  collision postfixing, since that renames the whole directory). Supporting
+  files carry no frontmatter contract and no audit header — they land
+  byte-identical to what the gem ships, with provenance and a per-file sha
+  recorded in `.hyperdrive/lock.yml` under the new `skill_support` kind. The
+  full drift state machine applies per file (unedited upgrades rewritten,
+  local edits skipped on sync / restored with `--overwrite`, deletions
+  reinstalled), a supporting file the gem stops shipping is cleaned up when
+  unedited (warned about and left when edited), disabling a skill removes its
+  unedited supporting files too, and the install summary shows them as a
+  `(+N files)` count on the skill's line.
+
+- `hyperdrive:sync` — content-only actualization. Refreshes skills, guidelines,
+  `index.md`, and `.hyperdrive/lock.yml` to match the current bundle, and
+  touches no bootstrap artifact (`.mcp.json`, the engine mount, the
+  optional initializer, the `.gitignore` rule). Locally-edited files are
+  preserved by default (skip + warn); pass `--overwrite` to restore the
+  gem-shipped content. Works with or without a prior `hyperdrive:init`.
+- An artifact's `gem:` frontmatter field can now declare **several** targets, as
+  either a comma-separated string (`gem: "sidekiq, solid_queue"`) or a YAML list.
+  The artifact installs when **any** listed target is in the bundle at a
+  satisfying version, so one guideline or skill can cover interchangeable
+  libraries instead of shipping as near-identical per-target copies. `"*"`
+  anywhere in the list makes the artifact universal.
+- `versions:` accepts a **map keyed by gem name** alongside the existing single
+  requirement, for target sets that do not share a version cycle:
+
+  ```yaml
+  gem: [sidekiq, solid_queue]
+  versions:
+    sidekiq: ">= 7.0"
+    solid_queue: ">= 1.0"
+  ```
+
+  A single requirement still applies to every listed target. Targets absent from
+  the map are unconstrained.
+- Content installation is now callable without a booted Rails application.
+  `Rails::Hyperdrive::InstallPipeline` takes an explicit application root and
+  performs the whole install — skills, guidelines, `index.md`, the `CLAUDE.md`
+  import line, and `.hyperdrive/lock.yml` — so any process that can
+  see the app's bundle can run it. `hyperdrive:init` and `hyperdrive:update`
+  call the same pipeline, and their behaviour is unchanged.
+- `Rails::Hyperdrive::ArtifactStatus` compares what the bundle offers against
+  what `.hyperdrive/lock.yml` records, classifying every artifact as
+  `installed`, `missing`, `outdated`, or `orphaned`.
+- `Rails::Hyperdrive::AutoInstall.run` tops up an already-initialized
+  application with artifacts the lockfile does not record yet, and returns
+  everything it deliberately left alone. Installation is strictly additive: it
+  can create a file that does not exist, and it will never overwrite one, so a
+  locally-edited artifact is safe. Upgraded and orphaned artifacts are reported
+  for `hyperdrive:update` to handle. It writes only when the environment reads
+  as development from `ENV` directly (no Rails to ask), `CI` is unset, and the
+  bundle is not frozen, and it reports errors rather than raising them.
+
+- `hyperdrive:init` / `hyperdrive:update` now check the *combined* eager
+  footprint against a budget, not just per-file size. When the guidelines
+  listed in `index.md` exceed ~10,000 tokens, the footprint line is followed
+  by a warning naming the two largest contributors, so it is
+  clear what to trim or which line to drop from `index.md` to opt a guideline
+  out. Individually reasonable guidelines could previously clear every per-file
+  check and still add up to real context-window pressure with nothing flagging
+  it. The install still proceeds — this is a warning, not a gate.
+
+- `hyperdrive:init` / `hyperdrive:update` now list every installed artifact in
+  the final summary, grouped under the source gem and version that shipped it,
+  instead of reporting bare skill and guideline counts. The listing is built
+  from `.hyperdrive/lock.yml`, so it reflects what the app ends up with —
+  including files left unchanged, files skipped as locally modified, and
+  orphans whose source gem has left the bundle — rather than only what the run
+  wrote. `--skip-content` prints no listing, as before.
+
+- `hyperdrive:init` / `hyperdrive:update` now warn when git ignores an install
+  destination. Installed artifacts are git-tracked on purpose: reviewing the
+  diff is how you see what a companion gem added to the agent's context. An app
+  that gitignores `.claude/` empties that diff while the artifacts still reach
+  the agent, and nothing previously said so. The check asks git whether each
+  destination is ignored, so patterns, negations, and per-repository excludes
+  are all honored; outside a git repository, or without git installed, it stays
+  silent.
+
+- Per-artifact opt-out via a `disabled:` list in `.hyperdrive/lock.yml`, keyed by
+  artifact type (`skills:` / `guidelines:`). A listed artifact is never installed,
+  and one already on disk is removed on the next `hyperdrive:init` /
+  `hyperdrive:sync` — but only when the file still matches the content the lock
+  recorded, so a locally-modified artifact is reported and left in place instead.
+  Disabling a guideline also drops its line from `index.md`. For a name shipped by
+  more than one companion gem, the shipped name disables every variant and the
+  `--<source-gem>` postfixed name disables one. The list is hand-edited: the
+  generator reads it, carries it forward, and writes the empty scaffold on every
+  install so the key is discoverable. Previously the only control was
+  `--skip-content`, which suppresses all installed content at once.
+
+### Changed
+
+- **BREAKING:** the eager-content chain is now companion-driven.
+  `.claude/hyperdrive/index.md` and the `@.claude/hyperdrive/index.md` line in
+  `CLAUDE.md` are created only once a companion gem ships a guideline, and are
+  removed again when the last one leaves the bundle. A zero-companion
+  `hyperdrive:init` now writes `.mcp.json`, the `.gitignore` rule, the optional
+  initializer, the engine mount, and `.hyperdrive/lock.yml` — and nothing into
+  the agent's context window. On tear-down, `CLAUDE.md` is deleted only when it
+  is byte-identical to the file hyperdrive created; otherwise only hyperdrive's
+  own import line is removed and every other byte is left alone. An import line
+  you deleted by hand is still never re-added. `hyperdrive:sync` performs the
+  tear-down; the `bundler-rails-hyperdrive` plugin (additive) never removes anything.
+  Because a `bundle install` must not edit `CLAUDE.md`, the plugin now says so
+  when it installs the first guideline into an app that has no import line yet:
+  the guideline is on disk but out of context until you run
+  `bin/rails hyperdrive:sync`.
+- **BREAKING:** `hyperdrive:init` no longer accepts `--update` /
+  `--force-install`; it always preserves locally-edited files (skip + warn).
+  The conflict warning and the AutoInstall nudge now point at
+  `hyperdrive:sync`.
+- `hyperdrive:init`'s summary now reports the mounted MCP server and its tool
+  count.
+- `bundle install` (through the `bundler-rails-hyperdrive` plugin) no longer parses
+  `Gemfile.lock`.
+
+### Removed
+
+- **BREAKING:** `.claude/hyperdrive/stack.md` is no longer generated. Ask the
+  running server what the app's stack is instead — the `describe_app` MCP tool
+  and the `hyperdrive://stack-profile` resource answer it live, from the
+  resolved bundle, and can never go stale the way a written-once file does.
+
+  **Manual migration:** an app installed before this release keeps
+  `.claude/hyperdrive/stack.md` on disk, and `hyperdrive:init` / `hyperdrive:sync`
+  will report it as an orphan on every run. Delete the file and its
+  `.hyperdrive/lock.yml` entry by hand.
+- **BREAKING:** `hyperdrive:update` is removed (not deprecated) — use
+  `bin/rails hyperdrive:sync --overwrite`. Note the default flip: the routine
+  refresh (`hyperdrive:sync`) now preserves locally-edited files; overwriting
+  them is opt-in via `--overwrite`.
+
+### Fixed
+
+- The MCP endpoint no longer 403s local requests whose `Origin` port differs
+  from the server's (e.g. `Origin: http://localhost` against
+  `127.0.0.1:3000`). The `mcp` gem's `StreamableHTTPTransport` gained
+  default-on DNS-rebinding protection requiring a same-origin `host:port`
+  match; it is now disabled in favor of the engine's own Rack middleware,
+  which allows any `localhost` / `127.0.0.1` / `[::1]` origin regardless of
+  port. The `mcp` dependency floor moves to `~> 0.25` accordingly.
+
+- `.hyperdrive/lock.yml` now round-trips top-level keys it does not recognize.
+  Reading it selected only the known keys and writing it rebuilt the document from
+  scratch, so anything hand-added to the file was erased on the next run. Entries
+  under `files:` remain fully generated.
+
+- `BundlerArtifactDiscovery#version_matches?` now correctly parses the documented
+  comma-separated single-string form of `versions:` (e.g. `">= 7.0, < 9.0"`).
+  Previously, `Gem::Requirement.new` rejected that form with `BadRequirementError`
+  (subclass of `ArgumentError`), which was caught and silently treated as a
+  version mismatch — installation would skip the artifact with a misleading
+  "does not satisfy" warning. The YAML list form (`versions: [">= 7.0", "< 9.0"]`)
+  was unaffected and continues to work.
+
+- `hyperdrive:init` / `hyperdrive:update` now merge the `rails-hyperdrive` entry
+  into an existing `.mcp.json` instead of rendering a template over the whole
+  file. Any other MCP servers you have configured, and any sibling top-level
+  keys, are preserved; only `mcpServers["rails-hyperdrive"]` is managed. The
+  write is also silent — previously a project with a pre-existing `.mcp.json`
+  hit Thor's interactive `Overwrite? [Ynaqdhm]` prompt, which stalls CI and
+  agent runs and then discarded the other servers anyway. A re-run that changes
+  nothing writes nothing, and a `.mcp.json` that cannot be parsed is left
+  byte-for-byte intact with a warning rather than overwritten.
+
+### Changed
+
+- **BREAKING:** the `gem:` value reported for each installed skill by the
+  `describe_app` MCP tool and the `hyperdrive://stack-profile` resource is now an
+  **array** of every target that matched, rather than a single string. A
+  single-target artifact reports a one-element array. Consumers reading that
+  field as a string need updating.
+
+- Documented the companion gem contract rules the installer enforces but the
+  README omitted or misstated: the `hyperdrive_skills_dir` gemspec metadata
+  override (an additional skill root, not a replacement; `..` segments ignored),
+  the permissive failure model and where its warnings surface, within-gem
+  collapsing of same-`name:` artifacts, and both accepted forms of `versions:`.
+  Corrected the description of `name:` — it determines the installed path rather
+  than merely matching the file or directory stem.
+
+- **BREAKING:** renamed the three companion-gem gemspec metadata keys
+  `hyperdrive_targets`, `hyperdrive_artifacts`, and `hyperdrive_skills_dir` to
+  `rails_hyperdrive_targets`, `rails_hyperdrive_artifacts`, and
+  `rails_hyperdrive_skills_dir`. The old spellings are no longer read, with no
+  deprecated alias. Gemspec metadata is a single flat namespace shared by every
+  published gem, and the unprefixed `hyperdrive_*` prefix belongs to the
+  pre-existing, unrelated `hyperdrive` gem on rubygems — the contract is now
+  namespaced by the gem that defines it. Companion gems must update their
+  gemspecs to the new keys.
+
+- **BREAKING:** `hyperdrive:discover` now finds companions by the metadata they
+  declare rather than by their name. It queries rubygems for gems declaring
+  `rails_hyperdrive_targets` instead of searching for the `rails-hyperdrive-`
+  name prefix, so a companion published under its author's own namespace is
+  suggested on the same terms as a purpose-built one. The `rails-hyperdrive-`
+  prefix remains a recommended naming convention and no longer plays any part in
+  discovery. Target matching, version gating, caching, and the never-raise
+  offline behaviour are unchanged, and artifact installation was never
+  name-filtered, so nothing about `hyperdrive:init` / `hyperdrive:update`
+  changes.
+
+- **BREAKING:** renamed the `hyperdrive:init` / `hyperdrive:update` flag
+  `--skip-skills` to `--skip-content`. The old name is removed outright, with no
+  deprecated alias — it never described what the flag does. The flag skips *all*
+  installed content, not just skills: skills, guidelines, `index.md`,
+  the `CLAUDE.md` import line, and `.hyperdrive/lock.yml`, leaving only
+  `.mcp.json`, the discover-cache `.gitignore` rule, the optional initializer,
+  and the engine mount. Writing no lockfile is intentional and unchanged: the
+  lock is a manifest of installed content, and a later `hyperdrive:init` or
+  `hyperdrive:update` reconstructs the full state from scratch. Update any
+  scripts or CI invocations passing `--skip-skills`.
+
+- Dropped the `< 8.1` upper cap on the `railties` and `activerecord` runtime
+  dependencies — both are now floor-only (`>= 7.2`), so the gem installs against
+  Rails 8.1 and later without waiting on a new release. The gem uses only stable
+  public Rails APIs and degrades gracefully per-tool, so the cap was conservative
+  rather than load-bearing. CI now exercises Rails 8.1 in place of 8.0.
+
+## [0.2.0] - 2026-05-29
+
+### Added
+
+- `hyperdrive:discover` — read-only, networked command that suggests uninstalled
+  `rails-hyperdrive-*` companion gems for the app's stack. Queries the rubygems
+  search API, matches each companion's declared `hyperdrive_targets` against
+  `Gemfile.lock`, and prints the `bundle add` lines to run. Results cache to
+  `.hyperdrive/discover_cache.json` (24h TTL; `--refresh` busts it); offline or
+  rate-limited runs fall back to a stale cache or report "unavailable" without
+  failing. Ships dormant — returns nothing until companion gems exist on rubygems.
+- `hyperdrive:init` now adds a `.gitignore` rule for the discover cache.
+
+## [0.1.0] - 2026-05-29
+
+### Added
+
+- Initial release of `rails-hyperdrive`: a dev-only Rails engine that mounts an MCP
+  server at `/_hyperdrive/mcp` exposing introspection tools for AI coding agents.
+- `hyperdrive:init` generator that installs architecture skills and auto-discovers
+  per-gem skills.
+
+[Unreleased]: https://github.com/rails-hyperdrive/rails-hyperdrive/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.3.0
+[0.2.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.2.0
+[0.1.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bakaface
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,229 @@
+# Rails Hyperdrive
+
+> Dev-only Rails engine that bootstraps an MCP server + skills/guidelines for AI coding agents (Claude Code first).
+
+Rails Hyperdrive mounts an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server at `http://localhost:3000/_hyperdrive/mcp` in development, exposing **8 introspection tools** so AI agents stop guessing — they can eval Ruby, query the DB (read-only), tail logs, list models and routes, locate source, fetch docs, and snapshot the stack.
+
+It also ships a `hyperdrive:init` generator that discovers and installs **two artifact types** that companion gems ship under a documented contract:
+
+- **Skills** — lazy, model-invoked via Claude Code's native description matcher. Procedural ("how to write an idempotent Sidekiq job"). Installed to `.claude/skills/<name>/SKILL.md`.
+- **Guidelines** — eager, always in context via `@`-include from `CLAUDE.md`. Declarative ("this app uses Pundit, not CanCanCan"). Installed to `.claude/hyperdrive/guidelines/<name>.md`.
+
+**rails-hyperdrive is the mechanism; companion gems are the content.** rails-hyperdrive itself ships no skills or guidelines — only the contract and the discovery/install engine. Content comes from companion gems, conventionally named `rails-hyperdrive-<library>` (e.g. `rails-hyperdrive-sidekiq`) following the [RuboCop ecosystem](https://github.com/rubocop/rubocop) precedent.
+
+Built on the official [`mcp` gem](https://github.com/modelcontextprotocol/ruby-sdk). MIT-licensed.
+
+---
+
+## Golden path
+
+```bash
+# 1. Add the dev gem
+$ bundle add rails-hyperdrive --group=development
+
+# 2. (Optional) Add a companion gem for your stack
+$ bundle add rails-hyperdrive-sidekiq --group=development
+
+# 3. Run the generator
+$ bin/rails hyperdrive:init
+
+  create  .mcp.json
+  insert  config/routes.rb
+  create  .claude/hyperdrive/guidelines/jobs-sidekiq.md
+  create  .claude/skills/sidekiq-idempotency/SKILL.md
+  create  .claude/hyperdrive/index.md
+  create  CLAUDE.md
+  create  .hyperdrive/lock.yml
+   eager  1 guideline(s), ~240 tokens always in context
+
+    done  hyperdrive initialized
+  Mount: /_hyperdrive (in config/routes.rb)
+  Server: 8 MCP tools at http://localhost:3000/_hyperdrive/mcp
+  Installed 1 skill, 1 guideline
+
+    rails-hyperdrive-sidekiq@1.2.0
+      skill      sidekiq-idempotency
+      guideline  jobs-sidekiq
+
+# 4. Start the dev server
+$ bin/dev
+
+# 5. Open Claude Code in the project directory
+# → Claude Code reads .mcp.json, connects to http://localhost:3000/_hyperdrive/mcp
+# → agent has 8 tools, the eager guidelines (via CLAUDE.md), and the lazy skills
+```
+
+`hyperdrive:init` also registers the `bundler-rails-hyperdrive` Bundler plugin in your Gemfile. From then on, `bundle add rails-hyperdrive-<library>` lands the companion's artifacts on that very `bundle install` — no explicit sync. The plugin is additive only (it never touches an existing file); version bumps and orphaned artifacts are only reported, with a pointer to `bin/rails hyperdrive:sync`.
+
+Run `bin/rails hyperdrive:sync` any time (e.g. after `bundle update` or adding a companion gem) to refresh installed content to the current bundle. It touches no bootstrap artifact and leaves locally-modified files untouched (skip + warn); pass `--overwrite` to restore them to the gem-shipped content.
+
+Run `hyperdrive:discover` to find companion gems published for your stack that you haven't installed yet — it queries rubygems (read-only, results cached for 24h; `--refresh` re-queries) and prints the `bundle add` lines to run, then run `bin/rails hyperdrive:sync`. It never touches your Gemfile or makes network calls unless you invoke it.
+
+---
+
+## What ships
+
+### MCP tools (8)
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 1 | `run_ruby` | Eval Ruby in the booted Rails process, with timeout + output capture |
+| 2 | `run_sql` | Read-only SQL via the AR connection (refuses non-SELECT) |
+| 3 | `tail_logs` | Tail the last N lines of a log under `log/` (defaults to `log/<env>.log`) |
+| 4 | `list_models` | List Active Record model classes with columns/validations/associations |
+| 5 | `locate_source` | Resolve `Const` / `Const#method` / `Const.method` / `dep:<gem>` to a file:line |
+| 6 | `lookup_doc` | Look up RDoc for a symbol (via `ri`) |
+| 7 | `describe_app` | Snapshot: Rails/Ruby/DB versions + full `StackProfile` |
+| 8 | `list_routes` | All routes: HTTP verb, path, controller#action, named route |
+
+### Resources
+
+- `hyperdrive://stack-profile` — JSON of the resolved `StackProfile`
+- `hyperdrive://skills/{name}` — markdown body of each installed skill
+
+### Install layout
+
+```
+CLAUDE.md                              # user-owned; ONE injected line: @.claude/hyperdrive/index.md
+.claude/hyperdrive/
+  index.md                             # managed aggregator: @guidelines/<name>.md
+  guidelines/<name>.md                 # companion-shipped, frontmatter stripped, audit-headered
+.claude/skills/<name>/
+  SKILL.md                             # companion-shipped, frontmatter kept, audit-headered
+  <supporting files>                   # optional companion-shipped extras, installed as shipped (*.md.erb rendered)
+.hyperdrive/lock.yml                   # git-tracked manifest (source gem, version, content hash)
+```
+
+`CLAUDE.md` and `index.md` are the **eager chain** — they exist only because a companion gem ships a guideline, and both go when the last one leaves the bundle (the guideline file itself is left on disk and reported as an orphan). With no companion gems installed, `hyperdrive:init` writes `.mcp.json`, the `.gitignore` rule, the optional initializer, the engine mount, and `.hyperdrive/lock.yml` — and nothing into the agent's context window.
+
+Everything a companion gem contributes lands here git-tracked, so a diff is where you review what it added — the install summary names each artifact's source gem and version, and every SKILL.md and guideline carries the same provenance in an audit header. A skill's supporting files carry no header — they install byte-identical to the install-ready body (the shipped bytes; for `*.md.erb` templates, the rendered output), and their provenance and content hash live in `.hyperdrive/lock.yml` alone. `hyperdrive:init` warns if your app gitignores these paths, since that empties the diff without changing what reaches the agent. The `hyperdrive:discover` cache is the one file rails-hyperdrive adds to `.gitignore`.
+
+### Turning off a single artifact
+
+A companion gem you want for one skill but not another doesn't have to be all-or-nothing. Add the artifact's name to the `disabled:` list in `.hyperdrive/lock.yml` — it is written empty on every install, so the shape is already there:
+
+```yaml
+disabled:
+  skills:
+    - sidekiq-idempotency
+  guidelines:
+    - jobs-sidekiq
+```
+
+A disabled artifact is never installed, and one already on disk is removed on the next `hyperdrive:init` or `hyperdrive:sync` — but only if you haven't edited it. A locally-modified file is reported and left alone, for you to delete when you're ready. Disabling a skill removes its shipped supporting files under the same per-file rule; files you created yourself in the skill directory survive and keep the directory alive. Disabling a guideline also drops its line from `index.md`, so it leaves eager context along with the file.
+
+The list is yours to edit; the generator only reads it and carries it forward. Delete a name to get the artifact back on the next run. When two companion gems ship the same artifact name, both install under a `<name>--<source-gem>` suffix — the plain name disables both, the suffixed name disables one.
+
+To skip installed content wholesale instead, pass `--skip-content`.
+
+### Companion gem contract
+
+A companion gem ships artifacts under:
+
+```
+<gem-source>/lib/<gem_name>/hyperdrive/skills/<name>/SKILL.md       # skill (dir-per-skill)
+<gem-source>/lib/<gem_name>/hyperdrive/guidelines/<name>.md         # guideline (flat file)
+```
+
+Skills may ship under an additional root declared in gemspec metadata:
+
+```ruby
+spec.metadata["rails_hyperdrive_skills_dir"] = "extra/skills"   # optional; relative to the gem root
+```
+
+That root is searched **in addition to** the convention path, never instead of it, so an override never hides skills already shipped at the convention path. A value containing a `..` segment is ignored. Guidelines have no override — they are found only at the convention path.
+
+A skill is a **directory**, and it may ship more than `SKILL.md`. Everything else in the skill directory — nested however you like (`workflows/`, `references/`, `examples/`, …) — installs alongside it as **supporting files**, preserving the relative layout under `.claude/skills/<name>/`. Reference them from `SKILL.md` with directory-relative links; a cross-source name collision renames the whole installed directory, so those links keep working. Supporting files carry no frontmatter contract and no audit header — they install byte-identical to the install-ready body, which is what the gem ships (markdown, code, or binary alike) except for `*.md.erb` templates, which install as their rendered output. Each is tracked per file in `.hyperdrive/lock.yml`, so local edits are preserved on sync exactly like any other installed file. `SKILL.md` frontmatter remains the skill's sole schema surface. Guidelines stay single-file.
+
+Every artifact carries four required YAML frontmatter fields:
+
+```yaml
+---
+name: jobs-sidekiq                # kebab-case; determines the install path
+description: Background job conventions for Sidekiq.
+gem: sidekiq                      # TARGET gem(s), resolved + version-matched in the bundle
+versions: ">= 7.0, < 9.0"         # Gem::Requirement matched against the target gem
+---
+```
+
+`name:` is the artifact's identity, not a label — it is what the installer writes to disk (`.claude/skills/<name>/SKILL.md`, `.claude/hyperdrive/guidelines/<name>.md`). Keep it equal to the file or directory stem: if the two disagree the install still succeeds, but the artifact lands under `name:`. Within one gem, two artifacts of the same type declaring the same `name:` collapse to a single installed file; which one survives is not a guarantee to build on, so give each a distinct `name:`.
+
+`versions:` accepts a single comma-separated string (`">= 7.0, < 9.0"`), a YAML list (`[">= 7.0", "< 9.0"]`), or — for multi-target artifacts — a map keyed by gem name.
+
+`gem:` names the **targets** (each must be present in the bundle; its resolved version is matched against `versions:`). Use `railties` for "every Rails app" or the quoted `"*"` for "always applicable" (it must be quoted — bare `*` is a YAML alias and the file is skipped). `hyperdrive:init` discovers every such file across the bundle, version-matches it, and installs it with an audit header naming `source`, `sha256`, and `installed_at`. Guidelines are installed with their frontmatter stripped (they are `@`-included eagerly). When two gems ship a same-named artifact, both install, each postfixed by source gem.
+
+One artifact can cover several interchangeable libraries — write `gem:` as a comma-separated string or a YAML list, and it installs when **any** listed target is bundled at a satisfying version. `"*"` anywhere in the list makes the artifact universal. Give `versions:` a map keyed by gem name when the targets do not share a version cycle; targets the map omits are unconstrained.
+
+```yaml
+---
+name: jobs-conventions
+description: Background job conventions.
+gem: [sidekiq, solid_queue, good_job]
+versions:
+  sidekiq: ">= 7.0"
+  solid_queue: ">= 1.0"
+---
+```
+
+Draw the listed targets from the gem's own `hyperdrive_targets` (below): the gem-level declaration decides whether a companion is suggested at all, and an artifact naming a target the gemspec omits is unreachable for apps that have only that target.
+
+#### Gem-conditional skill content
+
+A multi-file skill can condition parts of itself on the app's bundle, so one skill tree serves apps with different gem sets. Both mechanisms are evaluated at discovery time, against the same resolved bundle that gates whole artifacts.
+
+**Per-file gating.** A `conditional:` map in `SKILL.md` frontmatter gates individual supporting files. Keys are dir-relative shipped paths; values take the same `gem:`/`versions:` forms as the artifact-level fields (single target, comma-separated string, YAML list, per-target `versions:` map, `"*"`), and the file installs when **any** listed target is bundled at a satisfying version. Unlike the artifact level, `versions:` is optional here — omitted means unconstrained. Files the map doesn't mention install unconditionally, and the supporting files themselves stay byte-identical to upstream — the condition lives entirely out-of-band.
+
+```yaml
+---
+name: layered-rails
+description: Layered architecture conventions.
+gem: railties
+versions: ">= 7.2"
+conditional:
+  references/gems/alba.md:
+    gem: alba
+  references/gems/jobs.md:
+    gem: [sidekiq, solid_queue]
+    versions:
+      sidekiq: ">= 7.0"
+---
+```
+
+A malformed condition **fails open**: the file installs unconditionally and the problem is reported with the other discovery warnings — a surplus reference file is harmless, a missing one breaks links from `SKILL.md`. A key naming no shipped file, or naming `SKILL.md` itself (the artifact-level `gem:`/`versions:` gate the whole skill), is warned about and ignored. The `conditional:` key ships through to the installed frontmatter unchanged.
+
+**ERB-templated markdown.** A file named `*.md.erb` in a skill directory — including `SKILL.md.erb` in place of `SKILL.md` — is rendered at install time and lands as plain `.md` (the `.erb` suffix is dropped; a `SKILL.md.erb` defines a skill exactly like `SKILL.md`, with frontmatter read from the rendered output). Templates see a sealed binding of exactly three helpers over the resolved bundle, nothing else:
+
+- `gem?("name")` / `gem?("name", ">= 2.0")` — is the gem bundled (at a satisfying version)?
+- `any_gem?("a", "b", …)` — is any of these bundled?
+- `gem_version("name")` — the resolved version as a String, or `nil`.
+
+Rendering uses ERB's trim mode, so `<%- if gem?("alba") -%>` … `<%- end -%>` control lines leave no blank lines behind. A template that fails to render is skipped with a warning (the whole skill, when it's `SKILL.md.erb`); when a plain file and a template would land at the same path, the plain file wins with a warning. `conditional:` keys refer to templates by their shipped `x.md.erb` name and gate them before rendering. Guidelines get no ERB support.
+
+Use ERB sparingly — condition reference manuals via `conditional:` and wrap link-table rows that point at gated files, but keep "consider adopting gem X" recommendations unconditional. An all-wrapped `.md.erb` renders to an empty file; to omit a file entirely, gate it with `conditional:` instead.
+
+Gated files appear and disappear as the bundle changes: `hyperdrive:init`/`hyperdrive:sync` install newly gated-in files and remove unedited gated-out ones. The auto top-up after `bundle install` adds newly gated-in files but never removes anything and never rewrites an already-installed file, so removals and re-rendered template output wait for the next `hyperdrive:sync`.
+
+Discovery never raises. An artifact with missing or malformed frontmatter, a missing required field, no declared target in the bundle, or every bundled target resolving outside `versions:` is skipped, and the reason is collected. `hyperdrive:init` and `hyperdrive:sync` print the collected reasons at the end of the run, under a yellow `warn` line reading `discovery skipped N artifact(s):`. A companion whose artifacts all fail therefore installs nothing and reports it only there — read that section first when a gem you expected to contribute produces no files.
+
+To be discoverable by `hyperdrive:discover` **before** it is installed, a companion also declares gemspec metadata (read remotely from rubygems, so the frontmatter inside the gem isn't visible yet):
+
+```ruby
+spec.metadata["rails_hyperdrive_targets"]   = "sidekiq"          # required; comma-sep, or "*" for always-applicable
+spec.metadata["rails_hyperdrive_artifacts"] = "guideline,skill"  # optional; presentational hint
+```
+
+`rails_hyperdrive_targets` is what makes a gem discoverable: `hyperdrive:discover` searches rubygems for gems declaring it, so a companion is found by what it declares rather than by what it is named. Naming it `rails-hyperdrive-<library>` is a recommended convention — it makes the gem legible in a Gemfile — but it plays no part in discovery, and a companion published under your own namespace is found on the same terms.
+
+`rails_hyperdrive_targets` is a coarse pre-install hint — it is never reconciled against the frontmatter `gem:`; once the gem is bundled, the frontmatter alone governs what installs.
+
+---
+
+## Safety
+
+Rails Hyperdrive is **dev-only**. The engine refuses to handle requests outside `Rails.env.development?` and enforces an origin allowlist (`localhost`, `127.0.0.1`, `[::1]`). See [SECURITY.md](SECURITY.md).
+
+---
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/SECURITY.md

@@ -0,0 +1,43 @@
+# Security Model
+
+`rails-hyperdrive` is a **development-only** tool. Its security model is designed for a single developer running a Rails app on their own machine — nothing more. Read this before exposing your dev server to a network you don't fully control.
+
+## Threat model in one paragraph
+
+Rails Hyperdrive mounts an MCP server that exposes Ruby eval, raw SQL (read-only guardrail, not a sandbox), log tailing, and source-code introspection. It is intended to be reached from `http://localhost:3000/_hyperdrive/mcp` by a local AI coding agent (Claude Code) running on the same workstation. There is no authentication. If the dev server is reachable by another process, user, or host, that party can read everything in your Rails app and run arbitrary Ruby in your dev environment.
+
+## Three layers of defense
+
+All three layers key off `Rails::Hyperdrive.dev_mode?` (which is `Rails.env.development?`).
+
+1. **Engine load-time warning.** The engine loads in any environment so a production process doesn't crash if `rails-hyperdrive` slips into the wrong Bundler group, but it logs a warning at boot when not in development.
+
+2. **Rack middleware** (`Rails::Hyperdrive::Safety::RackMiddleware`) sits in front of the MCP transport on every request:
+   - Returns `403` when `Rails.env` is not `development`.
+   - Returns `403` when the `Origin` header is set and its host is not in the allowlist (`localhost`, `127.0.0.1`, `[::1]`). Requests with no `Origin` (e.g. `curl`, `Rack::Test`) pass through.
+
+3. **Per-tool `with_dev_guard`** in `Rails::Hyperdrive::Tools::Base` catches direct in-process invocations (tests, rake tasks) that would bypass the transport entirely.
+
+## What the Origin allowlist does and doesn't do
+
+The allowlist blocks DNS-rebinding attacks: an attacker can't trick a victim's browser into POSTing JSON-RPC to `http://localhost:3000/_hyperdrive/mcp` from an attacker-controlled origin, because the browser would attach `Origin: http://evil.example` and we'd 403 it.
+
+It does **not** authenticate anything. Any local process that can speak HTTP to your dev server can call every tool. If you run untrusted code on the same workstation, do not run `rails-hyperdrive`.
+
+## What `run_sql` actually is
+
+A best-effort regex-based gate that rejects mutating SQL at the parser level. It is **not** a sandbox. A determined attacker with `run_ruby` access can trivially bypass it (`run_ruby` runs arbitrary Ruby in the Rails process). The SQL guard exists to keep a confused AI from running `DELETE FROM users` by accident, not to enforce a privilege boundary.
+
+## Network exposure is your responsibility
+
+Rails Hyperdrive does not bind to a network interface — that is Puma's job. The default `bin/rails server` binding behavior varies by Rails version, operating system, and your `config/puma.rb`. To be safe:
+
+- Bind Puma to `127.0.0.1` (the default in recent Rails versions), not `0.0.0.0`.
+- Do not run `bin/rails server -b 0.0.0.0` on a network you share with untrusted parties.
+- Do not forward port 3000 in Docker / `kubectl port-forward` / `ngrok` / Tailscale / VPN unless you understand who can reach it.
+
+If you must expose the dev server, put it behind your own authenticating proxy and remove `rails-hyperdrive` from the bundle first.
+
+## Reporting a vulnerability
+
+Open a GitHub issue describing the impact. Do not include credentials or proprietary code. For sensitive reports, email the gem author listed in `rails-hyperdrive.gemspec`.

data/config/routes.rb

@@ -0,0 +1,5 @@
+require "rails/hyperdrive/mcp_server"
+
+Rails::Hyperdrive::Engine.routes.draw do
+  mount Rails::Hyperdrive::McpServer.rack_app => "/mcp", as: :mcp
+end