rails-hyperdrive 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3fbb6e0845e6194c6b33334e2bd03db6629cd61a8bfd973f8be3ce7b82fd1be
-  data.tar.gz: 8f259097744b8729ef71756df833809ff315305bf52a822ca1e40fa94298bc26
+  metadata.gz: 11be45047a967ade290022f1aa91cd023bf6085e0c84b4f6c08807d9b29f446b
+  data.tar.gz: 68205915ef162cc1006685361cb14e1690dcd82b666fbab12a54fdf7d5f26e2a
 SHA512:
-  metadata.gz: 3986cc09cecd60a44ecc9899be526c3db981d635a8bc458de956965b227fe51a2d3d4efc8e6da03f8016fc83320d59235d975a2ccdb22d4e86d6d75d7296e970
-  data.tar.gz: 4524e73cd275471bc2e555ff6845b31b3e4b96f75839bd5629b59611522e85d3dd224c4cc5b197f9a38d1ecf66a6fa9961d9ea60567c9626bb90ff46cc2825de
+  metadata.gz: 59852c94a50743b1666ab4c8d973b3a34d5178158e57c7b7e20c98e203c53dca22ac6ef505880f0b5b013b5972f9c2aa66b53ec2b1646eab2b6fef487bd4447a
+  data.tar.gz: 37165dc674f138b5f29bd408917f0d4d2e5847079f2f346fcc99d4341d2984d01eea3a228bfb434a0351d8c32115762bfbc5937f296a338e511726be4552c3a4

data/CHANGELOG.md

@@ -7,6 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-15
+
+### Added
+
+- Gem-root manifest: a companion gem now declares artifact gating in a
+  `hyperdrive.yml` at its root (or at the path named by a new
+  `rails_hyperdrive_manifest` gemspec metadata key; `..` segments or a blank
+  value fall back to the conventional path). Top-level `gem:`/`versions:` are
+  gem-wide defaults; `skills:` entries (keyed by skill-dir relpath from the
+  skills root) and `guidelines:` entries (keyed by filename) override them per
+  key, and per-file `conditional:` gating nests inside `skills:` entries. All
+  keys optional; malformed gating fails open (warn + install ungated, never
+  skip, never raise), and an entry keying no shipped artifact warns — the
+  staleness signal for gating detached from content. Shipping a manifest (file
+  or metadata key) is also a companion opt-in signal, so a skills.sh-format
+  skill repo integrates with zero modification to its skill files.
+
+- Template/content pairing for skills, so one companion repo can serve
+  `npx skills` / git-clone consumers and rails-hyperdrive at once without
+  giving up bundle-conditioned content. A skill directory holding a static
+  `SKILL.md` (the universal face: generated definition plus all supporting
+  files) pairs with a `SKILL.md.erb` master at the same relative path under a
+  templates root — declared via the new `rails_hyperdrive_skill_templates_dir`
+  gemspec metadata key, defaulting to the convention path
+  `lib/<gem_name>/hyperdrive/skills`. The pair discovers as one skill:
+  hyperdrive renders the template against the app's bundle and installs the
+  supporting files from the content directory, never reading the static
+  `SKILL.md`. Unpaired layouts — every existing companion — behave exactly as
+  before.
+- Canonical-render rake tasks for companion repos:
+  `require "rails/hyperdrive/skill_tasks"` in the Rakefile provides
+  `rake hyperdrive:skills:render` (generate each template's static `SKILL.md`
+  with the fail-open canonical binding — every gem present, `gem_version`
+  `nil`; the generated face carries only the skills.sh frontmatter, with the
+  installer-only `gem:`/`versions:`/`conditional:` keys stripped, as they are
+  on install) and `rake hyperdrive:skills:check` (fail listing stale generated
+  files — the CI freshness gate). Rails-free; rails-hyperdrive as a
+  development dependency suffices.
+- A gem's top-level `skills/` directory is now scanned as a default skills
+  root for opted-in companions (convention-path artifacts, a
+  `rails_hyperdrive_skills_dir`, `rails_hyperdrive_skill_templates_dir`, or
+  `rails_hyperdrive_targets` metadata key, or a lockfile `enabled:` entry are
+  the opt-in signals). Roots are deduplicated
+  by expanded path, so a companion already declaring
+  `rails_hyperdrive_skills_dir: "skills"` sees identical results.
+- A hand-editable `enabled:` list in `.hyperdrive/lock.yml` (gem names,
+  mirroring `disabled:`): naming a gem there treats it as an opted-in
+  companion, so its top-level `skills/` content installs through the normal
+  pipeline. `disabled:` still wins for individual artifacts.
+- `hyperdrive:init` and `hyperdrive:sync` now surface bundled gems that ship
+  skills.sh-style `skills/*/SKILL.md` content without opting in as companions
+  — report-only, with a pointer to the `enabled:` list; nothing is installed
+  until the user opts in.
+
+### Changed
+
+- The artifact frontmatter contract is relaxed to the skills.sh base
+  contract: only `name` and `description` are required. `gem:` and
+  `versions:` are now optional narrowing keys — a missing `gem:` means
+  universal (`"*"`), a missing `versions:` means unconstrained. Artifacts
+  declaring all four fields behave exactly as before.
+- **Breaking:** gating moved entirely to the gem-root manifest. The
+  frontmatter `gem:`/`versions:`/`conditional:` keys are no longer read —
+  they are ordinary unknown keys, silently ignored and installed verbatim —
+  and installer-key stripping is removed: skill bodies now install, and
+  render canonically, byte-identical to their shipped (or ERB-rendered)
+  content, frontmatter included. Guideline frontmatter is still stripped on
+  install. A companion gating via frontmatter must move those keys into
+  `hyperdrive.yml`.
+
 ## [0.4.0] - 2026-08-08
 
 ### Added
@@ -353,7 +423,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `hyperdrive:init` generator that installs architecture skills and auto-discovers
   per-gem skills.
 
-[Unreleased]: https://github.com/rails-hyperdrive/rails-hyperdrive/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/rails-hyperdrive/rails-hyperdrive/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.5.0
 [0.4.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.4.0
 [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

data/README.md

@@ -121,7 +121,7 @@ CLAUDE.md                              # user-owned; ONE injected line: @.claude
   index.md                             # managed aggregator: @guidelines/<name>.md
   guidelines/<name>.md                 # companion-shipped, frontmatter stripped
 .claude/skills/<name>/
-  SKILL.md                             # companion-shipped, frontmatter kept minus installer keys
+  SKILL.md                             # companion-shipped, installed verbatim (frontmatter included)
   <supporting files>                   # optional companion-shipped extras, installed as shipped (*.md.erb rendered)
 .hyperdrive/lock.yml                   # git-tracked manifest (source gem, version, content hash)
 ```
@@ -152,6 +152,17 @@ The list is yours to edit; the generator only reads it and carries it forward. D
 
 To skip installed content wholesale instead, pass `--skip-content` to `hyperdrive:init`.
 
+### Opting into a gem's bundled skills
+
+Ordinary gems (not built as hyperdrive companions) sometimes ship a top-level `skills/` directory of [skills.sh](https://skills.sh)-style skills. Those are never installed automatically — `hyperdrive:init` and `hyperdrive:sync` only report them, e.g. `gem 'foo' ships 2 skills.sh skill(s)`. To install them, name the gem in the `enabled:` list in `.hyperdrive/lock.yml` and re-run `hyperdrive:sync`:
+
+```yaml
+enabled:
+  - foo
+```
+
+An enabled gem is treated as a companion from then on: its skills install through the normal pipeline (including on `bundle install`), and `disabled:` still wins for any individual artifact. The list is hand-edited like `disabled:` and survives every rewrite of the lockfile.
+
 ---
 
 ## Safety
@@ -162,29 +173,44 @@ Rails Hyperdrive is **dev-only**, enforced in depth: the engine refuses to handl
 
 ## Build a companion gem
 
-Ship markdown at a convention path, declare what it targets, publish. That's the whole contract:
+Ship markdown, declare what it targets, publish. That's the whole contract:
 
 ```
-lib/<gem_name>/hyperdrive/skills/<name>/SKILL.md       # skill (dir-per-skill, may ship supporting files)
+skills/<name>/SKILL.md                                 # skill (dir-per-skill, may ship supporting files)
 lib/<gem_name>/hyperdrive/guidelines/<name>.md         # guideline (flat file)
 ```
 
+Top-level `skills/` is the recommended home for skill content — it is the tool-agnostic face of your gem, readable by skills.sh and plain git-clone consumers as well as hyperdrive. `lib/<gem_name>/hyperdrive/` is hyperdrive-specific machinery: guidelines (no skills.sh analogue), ERB skill templates (`SKILL.md.erb` — raw ERB must not reach generic consumers, so keep it out of `skills/`), and legacy static skills (still scanned for back-compat).
+
+Frontmatter is pure [skills.sh](https://skills.sh) — only `name` and `description` are read, so a skill repo's content integrates without modification:
+
 ```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
 ---
 ```
 
-And to be suggested by `hyperdrive:discover` before anyone installs you:
+Gating — which bundles an artifact installs into — lives in a `hyperdrive.yml` manifest at the gem root (or at the path named by a `rails_hyperdrive_manifest` gemspec metadata key), never in the content. Every key is optional; no manifest (or an empty one) means everything installs universally:
+
+```yaml
+gem: sidekiq                # gem-wide default: TARGET gem(s), resolved + version-matched in the bundle
+versions: ">= 7.0, < 9.0"   # gem-wide default: Gem::Requirement matched against the target gem
+skills:                     # per-skill overrides, keyed by skill dir relative to its skills root
+  jobs-sidekiq:
+    versions: ">= 8.0"
+guidelines:                 # per-guideline overrides, keyed by filename
+  jobs.md:
+    gem: sidekiq
+```
+
+Shipping a `hyperdrive.yml` (or declaring `rails_hyperdrive_manifest`) opts your gem in as a companion. Also declare your targets in gemspec metadata — it opts your gem in too, and it is the pre-install targeting signal (how `hyperdrive:discover` suggests you before anyone installs you):
 
 ```ruby
 spec.metadata["rails_hyperdrive_targets"] = "sidekiq"
 ```
 
-The full contract — multi-target artifacts, multi-file skills, per-file gem gating, ERB-templated content, collision and dedup rules — lives in [docs/COMPANION_GEMS.md](docs/COMPANION_GEMS.md).
+The full contract — multi-target artifacts, multi-file skills, per-file gem gating, ERB-templated content, the template/content paired layout that also serves `npx skills` and git-clone consumers, collision and dedup rules — lives in [docs/COMPANION_GEMS.md](docs/COMPANION_GEMS.md).
 
 ---
 

data/lib/generators/hyperdrive/sync_runner.rb

@@ -1,7 +1,9 @@
 require "thor"
 require "rails/hyperdrive"
 require "rails/hyperdrive/bundler_artifact_discovery"
+require "rails/hyperdrive/install_layout"
 require "rails/hyperdrive/install_pipeline"
+require "rails/hyperdrive/lock_file"
 require "generators/hyperdrive/install_summary"
 
 module Rails
@@ -29,7 +31,9 @@ module Rails
         end
 
         def discover_artifacts(skip: false)
-          @artifacts ||= skip ? [] : ::Rails::Hyperdrive::BundlerArtifactDiscovery.discover(warnings: warnings)
+          @artifacts ||= skip ? [] : ::Rails::Hyperdrive::BundlerArtifactDiscovery.discover(
+            warnings: warnings, enabled_gems: enabled_gems, notices: notices
+          )
         end
 
         def install(mode:)
@@ -38,7 +42,8 @@ module Rails
             shell: @shell,
             artifacts: discover_artifacts,
             mode: mode,
-            warnings: warnings
+            warnings: warnings,
+            notices: notices
           )
           @pipeline.call
         end
@@ -59,6 +64,16 @@ module Rails
           @warnings ||= []
         end
 
+        def notices
+          @notices ||= []
+        end
+
+        def enabled_gems
+          @enabled_gems ||= ::Rails::Hyperdrive::LockFile.load(
+            File.join(root, ::Rails::Hyperdrive::InstallLayout::LOCK_PATH)
+          ).enabled_gems
+        end
+
         def lock_entries
           entries = []
           @pipeline&.lock&.each_entry { |e| entries << e }

data/lib/rails/hyperdrive/auto_install.rb

@@ -4,6 +4,7 @@ require "rails/hyperdrive/bundler_artifact_discovery"
 require "rails/hyperdrive/install_layout"
 require "rails/hyperdrive/install_pipeline"
 require "rails/hyperdrive/install_shell"
+require "rails/hyperdrive/lock_file"
 
 module Rails
   module Hyperdrive
@@ -46,7 +47,8 @@ module Rails
         return skip(:not_development) unless development?(env)
         return skip(:not_initialized) unless File.exist?(File.join(root, InstallLayout::LOCK_PATH))
 
-        artifacts = BundlerArtifactDiscovery.discover
+        enabled = LockFile.load(File.join(root, InstallLayout::LOCK_PATH)).enabled_gems
+        artifacts = BundlerArtifactDiscovery.discover(enabled_gems: enabled)
         status = ArtifactStatus.compare(root: root, artifacts: artifacts)
 
         installed = []

data/lib/rails/hyperdrive/bundler_artifact_discovery.rb

@@ -1,17 +1,17 @@
 require "yaml"
 require "bundler"
+require "rails/hyperdrive/gem_manifest"
 require "rails/hyperdrive/skill_template"
 
 module Rails
   module Hyperdrive
     module BundlerArtifactDiscovery
       SKILL_FILE_NAMES = ["SKILL.md", "SKILL.md.erb"].freeze
-      INSTALLER_KEY = /\A(?:gem|versions|conditional):/.freeze
 
       Artifact = Struct.new(
         :name, :description, :target_gem, :versions, :artifact_type,
         :source_gem, :path, :body, :spec_version, :support_files,
-        :source_root,
+        :source_root, :support_root,
         keyword_init: true
       ) do
         def skill?
@@ -34,17 +34,30 @@ module Rails
       module_function
 
       # Non-fatal problems are appended to `warnings` and the artifact is
-      # dropped; discovery never raises.
-      def discover(specs: nil, warnings: [])
+      # dropped; discovery never raises. A gem that has not opted in as a
+      # companion is never scanned — its skills.sh content is only reported
+      # through `notices`.
+      def discover(specs: nil, warnings: [], enabled_gems: [], notices: [])
         specs ||= safe_bundler_specs
+        enabled = Array(enabled_gems).map(&:to_s)
         resolved = specs.each_with_object({}) { |s, h| h[s.name.to_s] = s.version }
 
         candidates = []
         specs.each do |spec|
-          each_artifact_path(spec, warnings: warnings) do |path, type|
-            artifact = parse(path, source_spec: spec, type: type, resolved: resolved, warnings: warnings)
+          unless opted_in?(spec, enabled_gems: enabled)
+            notice_skills_sh_content(spec, notices: notices)
+            next
+          end
+          manifest = GemManifest.load(spec, warnings: warnings)
+          seen = { skill: [], guideline: [] }
+          each_artifact_path(spec, warnings: warnings) do |path, type, support_root, key|
+            seen[type] << key
+            gate = type == :skill ? manifest.skill_gate(key) : manifest.guideline_gate(key)
+            artifact = parse(path, source_spec: spec, type: type, resolved: resolved,
+              warnings: warnings, support_root: support_root, gate: gate)
             candidates << artifact if artifact
           end
+          warn_unknown_manifest_keys(manifest, spec, seen, warnings)
         end
 
         # Collapse same-name variants within one source gem (highest
@@ -55,29 +68,137 @@ module Rails
         end
       end
 
+      # Yields each candidate with its manifest join key: a skill's relpath
+      # from its skills root, a guideline's filename. Keys are collected before
+      # parsing, so a candidate later dropped (e.g. an ERB render failure)
+      # still counts as known to the manifest.
       def each_artifact_path(spec, warnings: [])
-        skill_paths(spec, warnings: warnings).each { |p| yield p, :skill }
-        guideline_paths(spec).each { |p| yield p, :guideline }
+        skill_paths(spec, warnings: warnings).each { |path, support_root, rel| yield path, :skill, support_root, rel }
+        guideline_paths(spec).each { |p| yield p, :guideline, nil, File.basename(p) }
+      end
+
+      # The staleness signal for gating detached from content: an entry
+      # matching nothing means a renamed or removed skill dir/guideline.
+      def warn_unknown_manifest_keys(manifest, spec, seen, warnings)
+        (manifest.skill_keys - seen[:skill]).each do |key|
+          warnings << "#{spec.name}: manifest skills entry '#{key}' names no shipped skill directory"
+        end
+        (manifest.guideline_keys - seen[:guideline]).each do |key|
+          warnings << "#{spec.name}: manifest guidelines entry '#{key}' names no shipped guideline"
+        end
       end
 
       def skill_paths(spec, warnings: [])
-        roots = [File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive", "skills")]
+        roots = [
+          File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive", "skills"),
+          File.join(spec.full_gem_path, "skills")
+        ]
         if (override = skills_dir_override(spec))
           roots << File.join(spec.full_gem_path, override)
         end
-        found = roots.flat_map { |root| Dir.glob(File.join(root, "**", "{SKILL.md,SKILL.md.erb}")) }.uniq
-        found.group_by { |p| File.dirname(p) }.flat_map do |dir, group|
-          next group unless group.size > 1
-          warnings << "skip #{File.join(dir, "SKILL.md.erb")}: SKILL.md in the same directory takes precedence"
-          group.select { |p| File.basename(p) == "SKILL.md" }
+
+        candidates = []
+        seen = {}
+        roots.each do |root|
+          Dir.glob(File.join(root, "**", "{SKILL.md,SKILL.md.erb}"))
+             .group_by { |p| File.dirname(p) }.each do |dir, group|
+            next if seen[File.expand_path(dir)]
+            seen[File.expand_path(dir)] = true
+            candidates << {
+              dir: dir,
+              rel: dir.delete_prefix(root).delete_prefix("/"),
+              path: resolve_same_dir_tie(dir, group, warnings)
+            }
+          end
+        end
+
+        pair_with_templates(candidates, spec, warnings: warnings)
+      end
+
+      def resolve_same_dir_tie(dir, group, warnings)
+        return group.first unless group.size > 1
+        warnings << "skip #{File.join(dir, "SKILL.md.erb")}: SKILL.md in the same directory takes precedence"
+        group.find { |p| File.basename(p) == "SKILL.md" }
+      end
+
+      # A dir holding a static SKILL.md pairs with <templates root>/<same
+      # relative path>/SKILL.md.erb in a distinct dir: the rendered template is
+      # the definition, the static dir the support root. The static SKILL.md is
+      # never parsed — falling back to it when the template fails to render
+      # would silently un-condition the skill.
+      def pair_with_templates(candidates, spec, warnings:)
+        templates_root = File.join(spec.full_gem_path, skill_templates_dir(spec))
+
+        pairs = {}
+        candidates.each do |cand|
+          next unless File.basename(cand[:path]) == "SKILL.md"
+          template_dir = File.expand_path(File.join(templates_root, cand[:rel]))
+          next if template_dir == File.expand_path(cand[:dir])
+          template = File.join(template_dir, "SKILL.md.erb")
+          next unless File.file?(template)
+          warn_template_extras(template_dir, warnings)
+          pairs[cand[:dir]] = { template: template, template_dir: template_dir }
+        end
+
+        consumed = pairs.values.map { |p| p[:template_dir] }
+        candidates.filter_map do |cand|
+          if (pair = pairs[cand[:dir]])
+            [pair[:template], cand[:dir], cand[:rel]]
+          elsif consumed.include?(File.expand_path(cand[:dir]))
+            nil
+          else
+            [cand[:path], File.dirname(cand[:path]), cand[:rel]]
+          end
         end
       end
 
+      # The content dir is the single source of truth for supporting files.
+      def warn_template_extras(template_dir, warnings)
+        extras = Dir.glob(File.join(template_dir, "**", "*"))
+                    .select { |f| File.file?(f) && f != File.join(template_dir, "SKILL.md.erb") }
+        return if extras.empty?
+        warnings << "#{template_dir}: ignoring #{extras.size} file(s) besides SKILL.md.erb; " \
+                    "supporting files ship in the paired content directory"
+      end
+
       def guideline_paths(spec)
         root = File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive", "guidelines")
         Dir.glob(File.join(root, "*.md"))
       end
 
+      # Many gemspecs package files via `git ls-files`, so a contributor-facing
+      # skills/ dir ships by accident — package contents don't signal consumer
+      # intent. Only an explicit signal makes a gem's content installable.
+      def opted_in?(spec, enabled_gems:)
+        return true if enabled_gems.include?(spec.name.to_s)
+        return true if metadata_present?(spec, "rails_hyperdrive_skills_dir")
+        return true if metadata_present?(spec, "rails_hyperdrive_skill_templates_dir")
+        return true if metadata_present?(spec, "rails_hyperdrive_targets")
+        return true if GemManifest.opt_in?(spec)
+
+        convention_root = File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive")
+        Dir.glob(File.join(convention_root, "skills", "**", "{SKILL.md,SKILL.md.erb}")).any? ||
+          Dir.glob(File.join(convention_root, "guidelines", "*.md")).any?
+      end
+
+      def metadata_present?(spec, key)
+        return false unless spec.respond_to?(:metadata)
+        raw = spec.metadata && spec.metadata[key]
+        !raw.to_s.strip.empty?
+      end
+
+      # Report-only, glob-only (no file reads): SKILL.md presence is the
+      # signal, and SKILL.md.erb is excluded — raw ERB is not skills.sh
+      # content. Parse problems surface as warnings once the gem is enabled.
+      def notice_skills_sh_content(spec, notices:)
+        found = Dir.glob(File.join(spec.full_gem_path, "skills", "**", "SKILL.md"))
+        return if found.empty?
+
+        count = found.map { |p| File.dirname(p) }.uniq.size
+        notices << "gem '#{spec.name}' ships #{count} skills.sh skill(s); add \"#{spec.name}\" to enabled: " \
+                   "in .hyperdrive/lock.yml and re-run bin/rails hyperdrive:sync to install them"
+      end
+
       # ".." segments are rejected to prevent escaping the gem root.
       def skills_dir_override(spec)
         return nil unless spec.respond_to?(:metadata)
@@ -87,7 +208,19 @@ module Rails
         raw.to_s
       end
 
-      def parse(path, source_spec:, type:, resolved:, warnings:)
+      def skill_templates_dir(spec)
+        default = File.join("lib", spec.name, "hyperdrive", "skills")
+        return default unless spec.respond_to?(:metadata)
+        raw = spec.metadata && spec.metadata["rails_hyperdrive_skill_templates_dir"]
+        return default if raw.nil? || raw.to_s.strip.empty?
+        return default if raw.to_s.split(%r{[/\\]}).include?("..")
+        raw.to_s
+      end
+
+      # Frontmatter's schema is exactly name and description; any other key is
+      # unknown to the parser and rides untouched in the installed body.
+      def parse(path, source_spec:, type:, resolved:, warnings:, gate:, support_root: nil)
+        support_root ||= File.dirname(path)
         body = File.read(path)
         if erb_template?(path)
           begin
@@ -103,25 +236,20 @@ module Rails
           return nil
         end
 
-        meta        = YAML.safe_load(frontmatter, permitted_classes: [Symbol]) || {}
+        # Date is permitted because unknown frontmatter keys are user content;
+        # a bare date value must not fail the parse.
+        meta        = YAML.safe_load(frontmatter, permitted_classes: [Symbol, Date]) || {}
         name        = meta["name"]
         description = meta["description"]
-        versions    = meta["versions"]
-
-        unless name && description && meta["gem"] && versions
-          warnings << "skip #{path}: missing a required field (name, description, gem, versions)"
-          return nil
-        end
 
-        targets = parse_targets(meta["gem"])
-        if targets.nil? || targets.empty?
-          warnings << "skip #{name} (from #{source_spec.name}): gem: must name a gem, a comma-separated list, or a YAML list"
+        unless name && description
+          warnings << "skip #{path}: missing a required field (name, description)"
           return nil
         end
 
-        matched = match_targets(targets, versions, resolved)
+        matched = match_targets(gate.targets, gate.versions, resolved)
         if matched.empty?
-          warnings << "skip #{name} (from #{source_spec.name}): #{no_match_reason(targets, versions, resolved)}"
+          warnings << "skip #{name} (from #{source_spec.name}): #{no_match_reason(gate.targets, gate.versions, resolved)}"
           return nil
         end
 
@@ -129,17 +257,18 @@ module Rails
           name: name.to_s,
           description: description.to_s,
           target_gem: matched,
-          versions: versions,
+          versions: gate.versions,
           artifact_type: type,
           source_gem: source_spec.name.to_s,
           path: path,
           body: body,
           spec_version: source_spec.version.to_s,
           source_root: source_spec.full_gem_path.to_s,
+          support_root: support_root,
           support_files:
             if type == :skill
               conditioned_support_files(
-                File.dirname(path), meta["conditional"],
+                support_root, gate.conditional,
                 resolved: resolved, warnings: warnings,
                 label: "#{name} (from #{source_spec.name})"
               )
@@ -147,7 +276,7 @@ module Rails
               []
             end
         )
-      rescue Psych::SyntaxError
+      rescue Psych::Exception
         warnings << "skip #{path}: malformed YAML frontmatter"
         nil
       end
@@ -185,7 +314,7 @@ module Rails
         shipped = files.map { |f| f[:path] }
         conditions.each_key do |key|
           if SKILL_FILE_NAMES.include?(key)
-            warnings << "#{label}: conditional key '#{key}' ignored; the skill's own gem:/versions: gate the whole skill"
+            warnings << "#{label}: conditional key '#{key}' ignored; the entry's own gem:/versions: gate the whole skill"
           elsif !shipped.include?(key)
             warnings << "#{label}: conditional key '#{key}' names no shipped supporting file"
           end
@@ -203,14 +332,14 @@ module Rails
           return true
         end
 
-        targets = entry["gem"] && parse_targets(entry["gem"])
+        targets = entry["gem"] && GemManifest.parse_targets(entry["gem"])
         if targets.nil? || targets.empty?
           warnings << "#{label}: conditional entry for '#{key}' needs gem: naming a gem, a comma-separated list, or a YAML list; installing the file"
           return true
         end
 
         versions = entry["versions"]
-        if malformed_requirements?(versions)
+        if GemManifest.malformed_requirements?(versions)
           warnings << "#{label}: conditional entry for '#{key}' has an unparsable versions: requirement; installing the file"
           return true
         end
@@ -218,20 +347,6 @@ module Rails
         match_targets(targets, versions, resolved).any?
       end
 
-      # versions: is optional in a conditional entry; nil means unconstrained.
-      def malformed_requirements?(versions)
-        requirements = versions.is_a?(Hash) ? versions.values : [versions]
-        requirements.compact.any? do |req|
-          parts = Array(req).flat_map { |s| s.is_a?(String) ? s.split(",").map(&:strip) : s }
-          begin
-            Gem::Requirement.new(*parts)
-            false
-          rescue ArgumentError
-            true
-          end
-        end
-      end
-
       def render_support_templates(files, skill_dir, resolved:, warnings:)
         plain_paths = files.map { |f| f[:path] }
         files.filter_map do |file|
@@ -256,36 +371,15 @@ module Rails
         path.end_with?(".md.erb")
       end
 
+      # Guideline frontmatter is stripped because the installed file is
+      # @-included eagerly into agent context, where it would be inert noise.
       def install_ready_body(artifact)
-        return strip_installer_keys(artifact.body) if artifact.skill?
+        return artifact.body if artifact.skill?
 
         _frontmatter, rest = split_frontmatter(artifact.body)
         (rest || artifact.body).sub(/\A\n+/, "")
       end
 
-      # gem:/versions:/conditional: are install-time inputs with no reader
-      # after install, and conditional: keys name *shipped* paths that gating
-      # and ERB retargeting can leave pointing at files absent from disk — so
-      # the installed frontmatter carries neither.
-      def strip_installer_keys(body)
-        frontmatter, rest = split_frontmatter(body)
-        return body unless frontmatter
-
-        kept = []
-        skipping = false
-        frontmatter.lines.each do |line|
-          if line =~ INSTALLER_KEY
-            skipping = true
-          elsif skipping && (line.start_with?(" ", "\t") || line.strip.empty?)
-            # continuation of a stripped key's block
-          else
-            skipping = false
-            kept << line
-          end
-        end
-        "---\n#{kept.join}---\n#{rest}"
-      end
-
       def split_frontmatter(body)
         lines = body.lines
         return [nil, body] unless lines.first&.strip == "---"
@@ -297,12 +391,6 @@ module Rails
         [lines[1...absolute_closing].join, lines[(absolute_closing + 1)..].join]
       end
 
-      def parse_targets(raw)
-        entries = raw.is_a?(Array) ? raw : [raw]
-        return nil if entries.any? { |e| e.nil? || e.is_a?(Array) || e.is_a?(Hash) }
-        entries.flat_map { |e| e.to_s.split(",") }.map(&:strip).reject(&:empty?)
-      end
-
       def match_targets(targets, versions, resolved)
         return ["*"] if targets.include?("*")
 
@@ -334,13 +422,15 @@ module Rails
         []
       end
 
-      private_class_method :each_artifact_path, :skill_paths, :guideline_paths,
-                           :skills_dir_override, :parse, :support_files_for,
+      private_class_method :each_artifact_path, :warn_unknown_manifest_keys, :skill_paths,
+                           :guideline_paths,
+                           :resolve_same_dir_tie, :pair_with_templates, :warn_template_extras,
+                           :opted_in?, :metadata_present?, :notice_skills_sh_content,
+                           :skills_dir_override, :skill_templates_dir, :parse, :support_files_for,
                            :conditioned_support_files, :apply_conditional_filter,
-                           :conditional_satisfied?, :malformed_requirements?,
+                           :conditional_satisfied?,
                            :render_support_templates, :erb_template?,
-                           :strip_installer_keys,
-                           :split_frontmatter, :parse_targets, :match_targets,
+                           :match_targets,
                            :version_satisfied?, :no_match_reason, :safe_bundler_specs
     end
   end

data/lib/rails/hyperdrive/canonical_skill_render.rb

@@ -0,0 +1,105 @@
+require "fileutils"
+require "yaml"
+require "rails/hyperdrive/bundler_artifact_discovery"
+require "rails/hyperdrive/skill_template"
+
+module Rails
+  module Hyperdrive
+    # Renders each SKILL.md.erb template in a companion gem repo to the static
+    # SKILL.md it pairs with, using the canonical fail-open binding.
+    # Companion-repo dev tooling: problems raise.
+    module CanonicalSkillRender
+      Error = Class.new(StandardError)
+
+      Rendered = Struct.new(:template, :dest, :body, keyword_init: true)
+
+      module_function
+
+      def write(gemspec: nil, dir: Dir.pwd)
+        render_all(gemspec: gemspec, dir: dir).each do |r|
+          FileUtils.mkdir_p(File.dirname(r.dest))
+          File.write(r.dest, r.body)
+        end
+      end
+
+      def stale(gemspec: nil, dir: Dir.pwd)
+        render_all(gemspec: gemspec, dir: dir).reject do |r|
+          File.file?(r.dest) && File.read(r.dest) == r.body
+        end
+      end
+
+      def render_all(gemspec: nil, dir: Dir.pwd)
+        spec_path = resolve_gemspec_path(gemspec, dir)
+        spec = Gem::Specification.load(spec_path)
+        raise Error, "could not load gemspec #{spec_path}" unless spec
+
+        gem_root = File.dirname(File.expand_path(spec_path))
+        skills_root = File.join(gem_root, metadata_dir(spec, "rails_hyperdrive_skills_dir"))
+        templates_root = File.join(gem_root, metadata_dir(spec, "rails_hyperdrive_skill_templates_dir"))
+
+        Dir.glob(File.join(templates_root, "**", "SKILL.md.erb")).sort.map do |template|
+          rel = File.dirname(template).delete_prefix(templates_root).delete_prefix("/")
+          dest_dir = File.join(skills_root, rel)
+          # A SKILL.md written beside the SKILL.md.erb would take precedence
+          # over it at discovery time, silently demoting the skill to its
+          # static face.
+          if File.expand_path(dest_dir) == File.expand_path(File.dirname(template))
+            raise Error, "#{template}: content dir equals template dir; set " \
+                         "spec.metadata[\"rails_hyperdrive_skills_dir\"] to a separate root"
+          end
+
+          body = render_template(template)
+          validate_output!(body, template)
+          Rendered.new(template: template, dest: File.join(dest_dir, "SKILL.md"), body: body)
+        end
+      end
+
+      def resolve_gemspec_path(explicit, dir)
+        if explicit && !explicit.to_s.strip.empty?
+          path = File.expand_path(explicit.to_s, dir)
+          raise Error, "gemspec not found: #{path}" unless File.file?(path)
+          return path
+        end
+
+        found = Dir.glob(File.join(dir, "*.gemspec"))
+        case found.size
+        when 1 then File.expand_path(found.first)
+        when 0 then raise Error, "no .gemspec found in #{dir}; pass an explicit path, " \
+                                 "e.g. rake \"hyperdrive:skills:render[path/to/name.gemspec]\""
+        else raise Error, "multiple gemspecs found in #{dir} " \
+                          "(#{found.map { |f| File.basename(f) }.join(", ")}); pass an explicit path"
+        end
+      end
+
+      def metadata_dir(spec, key)
+        default = File.join("lib", spec.name, "hyperdrive", "skills")
+        raw = spec.metadata && spec.metadata[key]
+        return default if raw.nil? || raw.to_s.strip.empty?
+        raise Error, "gemspec metadata #{key} must not contain '..' segments" if
+          raw.to_s.split(%r{[/\\]}).include?("..")
+        raw.to_s
+      end
+
+      def render_template(template)
+        SkillTemplate.render_canonical(File.read(template))
+      rescue SyntaxError, StandardError => e
+        raise Error, "#{template}: canonical render failed (#{e.message})"
+      end
+
+      # A static face with unusable frontmatter would ship a broken skill to
+      # consumers that read it directly.
+      def validate_output!(body, template)
+        frontmatter, = BundlerArtifactDiscovery.split_frontmatter(body)
+        raise Error, "#{template}: rendered output has no YAML frontmatter" unless frontmatter
+
+        meta = YAML.safe_load(frontmatter, permitted_classes: [Symbol]) || {}
+        return if meta["name"] && meta["description"]
+        raise Error, "#{template}: rendered frontmatter lacks name: or description:"
+      rescue Psych::SyntaxError
+        raise Error, "#{template}: rendered frontmatter is not parseable YAML"
+      end
+
+      private_class_method :resolve_gemspec_path, :metadata_dir, :render_template, :validate_output!
+    end
+  end
+end

data/lib/rails/hyperdrive/gem_manifest.rb

@@ -0,0 +1,175 @@
+require "yaml"
+
+module Rails
+  module Hyperdrive
+    # A companion gem's root manifest (hyperdrive.yml) declares artifact
+    # gating: top-level gem:/versions: defaults for the whole gem,
+    # per-skill entries keyed by the skill dir's relative path from its skills
+    # root, per-guideline entries keyed by filename. Fail-open at every level:
+    # malformed input warns and resolves to an ungated install — an artifact is
+    # never skipped because its gating could not be read, and nothing raises.
+    class GemManifest
+      FILE_NAME = "hyperdrive.yml"
+      METADATA_KEY = "rails_hyperdrive_manifest"
+
+      UNGATED = ["*"].freeze
+
+      Gate = Struct.new(:targets, :versions, :conditional, keyword_init: true)
+
+      class << self
+        def load(spec, warnings: [])
+          new(spec, warnings: warnings)
+        end
+
+        # The metadata key counts even when its value is unusable — declaring
+        # it at all signals companion intent.
+        def opt_in?(spec)
+          return true if File.file?(File.join(spec.full_gem_path, FILE_NAME))
+          return false unless spec.respond_to?(:metadata)
+
+          raw = spec.metadata && spec.metadata[METADATA_KEY]
+          !raw.to_s.strip.empty?
+        end
+
+        def parse_targets(raw)
+          entries = raw.is_a?(Array) ? raw : [raw]
+          return nil if entries.any? { |e| e.nil? || e.is_a?(Array) || e.is_a?(Hash) }
+          entries.flat_map { |e| e.to_s.split(",") }.map(&:strip).reject(&:empty?)
+        end
+
+        # versions: is optional everywhere; nil means unconstrained.
+        def malformed_requirements?(versions)
+          requirements = versions.is_a?(Hash) ? versions.values : [versions]
+          requirements.compact.any? do |req|
+            parts = Array(req).flat_map { |s| s.is_a?(String) ? s.split(",").map(&:strip) : s }
+            begin
+              Gem::Requirement.new(*parts)
+              false
+            rescue ArgumentError
+              true
+            end
+          end
+        end
+      end
+
+      def initialize(spec, warnings:)
+        @spec = spec
+        @warnings = warnings
+        root = load_root
+        @skills = section(root, "skills", "skill relpath")
+        @guidelines = section(root, "guidelines", "guideline filename")
+        @default_targets, @default_versions = defaults(root)
+      end
+
+      def skill_gate(rel)
+        return default_gate unless @skills.key?(rel)
+        entry_gate(@skills[rel], rel, with_conditional: true)
+      end
+
+      def guideline_gate(filename)
+        return default_gate unless @guidelines.key?(filename)
+        entry_gate(@guidelines[filename], filename, with_conditional: false)
+      end
+
+      def skill_keys
+        @skills.keys
+      end
+
+      def guideline_keys
+        @guidelines.keys
+      end
+
+      private
+
+      def report(message)
+        @warnings << "#{@spec.name}: #{message}"
+      end
+
+      # ".." segments are rejected (silent fallback to the conventional path)
+      # to prevent escaping the gem root.
+      def manifest_relpath
+        return FILE_NAME unless @spec.respond_to?(:metadata)
+        raw = @spec.metadata && @spec.metadata[METADATA_KEY]
+        return FILE_NAME if raw.nil? || raw.to_s.strip.empty?
+        return FILE_NAME if raw.to_s.split(%r{[/\\]}).include?("..")
+        raw.to_s
+      end
+
+      # An empty file is a valid manifest (nothing gated); only content that
+      # cannot be read as a YAML map warns.
+      def load_root
+        path = File.join(@spec.full_gem_path, manifest_relpath)
+        return {} unless File.file?(path)
+
+        data = YAML.safe_load(File.read(path), permitted_classes: [Symbol])
+        return {} if data.nil?
+        unless data.is_a?(Hash)
+          report("ignoring manifest #{manifest_relpath}: root must be a YAML map")
+          return {}
+        end
+        data.transform_keys(&:to_s)
+      rescue Psych::SyntaxError
+        report("ignoring manifest #{manifest_relpath}: malformed YAML")
+        {}
+      rescue StandardError => e
+        report("ignoring manifest #{manifest_relpath}: unreadable (#{e.message})")
+        {}
+      end
+
+      def section(root, key, key_label)
+        value = root[key]
+        return {} if value.nil?
+        unless value.is_a?(Hash)
+          report("manifest #{key}: must be a map of #{key_label} to {gem:, versions:}; ignoring the section")
+          return {}
+        end
+        value.transform_keys(&:to_s)
+      end
+
+      def defaults(root)
+        targets = root.key?("gem") ? self.class.parse_targets(root["gem"]) : nil
+        bad_targets = root.key?("gem") && (targets.nil? || targets.empty?)
+        if bad_targets || self.class.malformed_requirements?(root["versions"])
+          report("manifest top-level gem:/versions: defaults are unusable; ignoring them")
+          return [nil, nil]
+        end
+        [targets, root["versions"]]
+      end
+
+      def default_gate
+        Gate.new(targets: @default_targets || UNGATED, versions: @default_versions, conditional: nil)
+      end
+
+      def ungated
+        Gate.new(targets: UNGATED, versions: nil, conditional: nil)
+      end
+
+      # A malformed entry drops the gem-wide defaults too: gating that cannot
+      # be read must not skip the artifact, so it installs ungated.
+      def entry_gate(entry, key, with_conditional:)
+        unless entry.is_a?(Hash)
+          report("manifest entry for '#{key}' must be a map with gem:/versions:; installing ungated")
+          return ungated
+        end
+
+        entry = entry.transform_keys(&:to_s)
+        targets = entry.key?("gem") ? self.class.parse_targets(entry["gem"]) : nil
+        if entry.key?("gem") && (targets.nil? || targets.empty?)
+          report("manifest entry for '#{key}': gem: must name a gem, a comma-separated list, " \
+                 "or a YAML list; installing ungated")
+          return ungated
+        end
+        if self.class.malformed_requirements?(entry["versions"])
+          report("manifest entry for '#{key}' has an unparsable versions: requirement; installing ungated")
+          return ungated
+        end
+
+        Gate.new(
+          targets: targets || @default_targets || UNGATED,
+          versions: entry.key?("versions") ? entry["versions"] : @default_versions,
+          conditional: with_conditional ? entry["conditional"] : nil
+        )
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/install_pipeline.rb

@@ -26,7 +26,7 @@ module Rails
       Result = Struct.new(:installed, :updated, :unchanged, :skipped, :orphaned, :removed, :merged, :sidecars,
         keyword_init: true)
 
-      def initialize(root:, shell:, artifacts:, mode: :preserve, warnings: [])
+      def initialize(root:, shell:, artifacts:, mode: :preserve, warnings: [], notices: [])
         raise ArgumentError, "unknown mode #{mode.inspect}" unless MODES.include?(mode)
 
         @root = File.expand_path(root.to_s)
@@ -34,6 +34,7 @@ module Rails
         @artifacts = artifacts
         @mode = mode
         @warnings = warnings
+        @notices = notices
         @result = Result.new(
           installed: [], updated: [], unchanged: [], skipped: [], orphaned: [], removed: [], merged: [], sidecars: []
         )
@@ -54,6 +55,7 @@ module Rails
         write_claude_md(guidelines)
         write_lock
         print_warnings
+        print_notices
         print_footprint(guidelines: eager_guidelines)
         warn_if_destinations_gitignored
         @result
@@ -115,6 +117,7 @@ module Rails
       def install_skills
         @plan.select { |e| e.type == :skill }.each do |entry|
           skill_relpath = source_relpath_for(entry.artifact)
+          support_base = support_relpath_base(entry.artifact, skill_relpath)
           install_file(entry: entry, type: :skill, install_ready_body: entry.install_ready_body,
             source_relpath: skill_relpath, final_name: entry.final_name)
           entry.support_files.each do |file|
@@ -125,7 +128,7 @@ module Rails
               source_gem: entry.source_gem,
               version: entry.version,
               artifact_kind: "skill_support",
-              source_relpath: skill_relpath && File.join(File.dirname(skill_relpath), file[:path])
+              source_relpath: support_base && File.join(support_base, file[:path])
             )
           end
         end
@@ -155,6 +158,22 @@ module Rails
         rel.end_with?(".md.erb") ? rel.delete_suffix(".erb") : rel
       end
 
+      # Supporting files live under the artifact's support root, which for a
+      # template-paired skill is not the definition file's directory.
+      def support_relpath_base(artifact, skill_relpath)
+        support_root = artifact.support_root
+        return skill_relpath && File.dirname(skill_relpath) if support_root.nil? || support_root.to_s.empty?
+
+        root = artifact.source_root
+        return nil if root.nil? || root.to_s.empty?
+
+        prefix = "#{File.expand_path(root.to_s)}/"
+        expanded = File.expand_path(support_root.to_s)
+        return nil unless expanded.start_with?(prefix)
+
+        expanded.delete_prefix(prefix)
+      end
+
       def install_file(dest: nil, type:, install_ready_body:, entry: nil, source_gem: nil, version: nil,
                        artifact_kind: nil, source_relpath: nil, final_name: nil)
         write = {
@@ -524,6 +543,12 @@ module Rails
         @warnings.each { |w| @shell.say "    - #{w}" }
       end
 
+      def print_notices
+        return if additive? || Array(@notices).empty?
+        @shell.say ""
+        @notices.each { |n| @shell.say_status :info, n, :blue }
+      end
+
       def print_footprint(guidelines:)
         return if additive?
 

data/lib/rails/hyperdrive/lock_file.rb

@@ -33,6 +33,7 @@ module Rails
         @files = {}            # path(String) => Entry
         @document = {}         # raw parsed YAML, kept so unknown keys survive
         @disabled = empty_disabled
+        @enabled = []
       end
 
       def read
@@ -45,6 +46,7 @@ module Rails
         claude_md = data["claude_md"]
         @claude_md_state = claude_md["state"] if claude_md.is_a?(Hash)
         @disabled = parse_disabled(data["disabled"])
+        @enabled = parse_enabled(data["enabled"])
         Array(data["files"]).each do |raw|
           next unless raw.is_a?(Hash)
           entry = build_entry(raw)
@@ -71,11 +73,17 @@ module Rails
         Array(@disabled[type.to_sym]).include?(name.to_s)
       end
 
+      # Hand-editable list of gems the app opts into as companions.
+      def enabled_gems
+        @enabled
+      end
+
       # Adopt the state that is not derived from installed content, so
       # rewriting the file preserves it.
       def carry_settings(other)
         @document = other.document.dup
         @disabled = other.disabled_lists.dup
+        @enabled = other.enabled_gems.dup
         self
       end
 
@@ -103,6 +111,7 @@ module Rails
           "version"   => SCHEMA_VERSION,
           "claude_md" => carried.merge("state" => @claude_md_state),
           "disabled"  => DISABLED_KEYS.each_with_object({}) { |(type, key), h| h[key] = @disabled[type] },
+          "enabled"   => @enabled,
           "files"     => @files.values.sort_by(&:path).map { |e| serialize_entry(e) }
         )
         # A nil state means no import line is being managed. Recording one anyway
@@ -136,6 +145,12 @@ module Rails
         end
       end
 
+      def parse_enabled(raw)
+        return [] unless raw.is_a?(Array)
+
+        raw.map { |name| name.to_s.strip }.reject(&:empty?).uniq
+      end
+
       def build_entry(raw)
         source_gem, source_version = split_source(raw["source"])
         Entry.new(

data/lib/rails/hyperdrive/skill_tasks.rb

@@ -0,0 +1,27 @@
+# Rake tasks for companion gem repos: add `require "rails/hyperdrive/skill_tasks"`
+# to the Rakefile. Both tasks take an optional gemspec-path argument, e.g.
+# rake "hyperdrive:skills:render[path/to/name.gemspec]".
+require "rake"
+require "rails/hyperdrive/canonical_skill_render"
+
+namespace :hyperdrive do
+  namespace :skills do
+    desc "Render each SKILL.md.erb template to its canonical static SKILL.md"
+    task :render, [:gemspec] do |_t, args|
+      written = Rails::Hyperdrive::CanonicalSkillRender.write(gemspec: args[:gemspec])
+      written.each { |r| puts "render #{r.dest}" }
+      puts "no skill templates found" if written.empty?
+    end
+
+    desc "Fail when a canonical SKILL.md is stale relative to its template"
+    task :check, [:gemspec] do |_t, args|
+      stale = Rails::Hyperdrive::CanonicalSkillRender.stale(gemspec: args[:gemspec])
+      if stale.empty?
+        puts "canonical skill files up to date"
+      else
+        stale.each { |r| warn "stale: #{r.dest}" }
+        abort "#{stale.size} canonical skill file(s) stale; run `rake hyperdrive:skills:render`"
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/skill_template.rb

@@ -31,6 +31,27 @@ module Rails
         end
       end
 
+      # Fail-open binding for the canonical render: every gem reads as present
+      # at any requested version, so the output includes every conditional
+      # branch. There is no bundle to resolve against, so gem_version is nil.
+      class CanonicalContext
+        def gem?(_name, _requirement = nil)
+          true
+        end
+
+        def any_gem?(*)
+          true
+        end
+
+        def gem_version(_name)
+          nil
+        end
+
+        def template_binding
+          binding
+        end
+      end
+
       module_function
 
       # Errors (ERB SyntaxError included) propagate; the caller decides how to
@@ -39,6 +60,10 @@ module Rails
         ERB.new(source, trim_mode: "-").result(Context.new(resolved).template_binding)
       end
 
+      def render_canonical(source)
+        ERB.new(source, trim_mode: "-").result(CanonicalContext.new.template_binding)
+      end
+
       # Gem::Requirement.new does not parse a single comma-separated string, so
       # such strings are split into separate constraints first.
       def version_matches?(requirement_str, version)

data/lib/rails/hyperdrive/stack_profile.rb

@@ -130,7 +130,8 @@ module Rails
       # Bundler is absent or refuses to resolve.
       def gem_skills_info
         require "rails/hyperdrive/bundler_artifact_discovery"
-        ::Rails::Hyperdrive::BundlerArtifactDiscovery.discover.select(&:skill?).map do |skill|
+        discovered = ::Rails::Hyperdrive::BundlerArtifactDiscovery.discover(enabled_gems: enabled_gems)
+        discovered.select(&:skill?).map do |skill|
           {
             name: skill.name,
             gem: skill.target_gem,
@@ -143,6 +144,24 @@ module Rails
       rescue StandardError
         []
       end
+
+      def enabled_gems
+        require "rails/hyperdrive/install_layout"
+        require "rails/hyperdrive/lock_file"
+        root =
+          if @app_root
+            @app_root.to_s
+          elsif defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+            ::Rails.root.to_s
+          end
+        return [] unless root
+
+        ::Rails::Hyperdrive::LockFile.load(
+          File.join(root, ::Rails::Hyperdrive::InstallLayout::LOCK_PATH)
+        ).enabled_gems
+      rescue StandardError
+        []
+      end
     end
   end
 end

data/lib/rails/hyperdrive/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Hyperdrive
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-hyperdrive
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Bakaface
@@ -100,12 +100,14 @@ files:
 - lib/rails/hyperdrive/artifact_status.rb
 - lib/rails/hyperdrive/auto_install.rb
 - lib/rails/hyperdrive/bundler_artifact_discovery.rb
+- lib/rails/hyperdrive/canonical_skill_render.rb
 - lib/rails/hyperdrive/claude_md_import.rb
 - lib/rails/hyperdrive/companion_discovery.rb
 - lib/rails/hyperdrive/console_executor.rb
 - lib/rails/hyperdrive/drift_verdict.rb
 - lib/rails/hyperdrive/eager_footprint.rb
 - lib/rails/hyperdrive/engine.rb
+- lib/rails/hyperdrive/gem_manifest.rb
 - lib/rails/hyperdrive/index_document.rb
 - lib/rails/hyperdrive/install_layout.rb
 - lib/rails/hyperdrive/install_pipeline.rb
@@ -116,6 +118,7 @@ files:
 - lib/rails/hyperdrive/resources/skill.rb
 - lib/rails/hyperdrive/resources/stack_profile.rb
 - lib/rails/hyperdrive/safety/rack_middleware.rb
+- lib/rails/hyperdrive/skill_tasks.rb
 - lib/rails/hyperdrive/skill_template.rb
 - lib/rails/hyperdrive/sql_safety.rb
 - lib/rails/hyperdrive/stack_profile.rb