belt 0.2.9 → 0.2.11

data/lib/belt_controller/base.rb

@@ -7,11 +7,13 @@ require_relative '../belt/helpers/response'
 require_relative '../belt/helpers/error_logging'
 require_relative '../belt/helpers/cors_origin'
 require_relative '../belt/rendering'
+require_relative 'implicit_response'
 
 module BeltController
   class Base
     include Belt::Helpers::Response
     include Belt::Rendering
+    include ImplicitResponse
 
     attr_reader :event, :body
 
@@ -48,6 +50,25 @@ module BeltController
         skipped_before_actions << { method: method_name, only: only&.map(&:to_sym), except: except&.map(&:to_sym) }
       end
 
+      # Implicit response format when the action does not call success_response /
+      # error_response / html_response / render / head.
+      # Inherits up the controller chain; falls back to Belt.configuration.default_format.
+      def default_format
+        return @default_format if defined?(@default_format)
+        return superclass.default_format if superclass.respond_to?(:default_format)
+
+        Belt.configuration.default_format
+      end
+
+      def default_format=(value)
+        format = value.to_sym
+        unless Belt::Configuration::VALID_FORMATS.include?(format)
+          raise ArgumentError, "default_format must be :json or :html (got #{value.inspect})"
+        end
+
+        @default_format = format
+      end
+
       def all_before_actions
         if superclass.respond_to?(:all_before_actions)
           superclass.all_before_actions + before_actions
@@ -115,9 +136,11 @@ module BeltController
       end
 
       run_before_actions(action_sym)
+      # Snapshot ivars so we only auto-serialize assigns set by the action (Rails-style)
+      @__assigns_before = instance_variables
       result = send(action_sym)
       run_after_actions(action_sym)
-      result
+      finalize_response(result)
     rescue StandardError => e
       handle_exception(e)
     end

data/lib/belt_controller/implicit_response.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module BeltController
+  # Rails-like implicit JSON/HTML responses from action assigns / return values.
+  # Included by BeltController::Base so the base class stays under Metrics/ClassLength.
+  module ImplicitResponse
+    # Never auto-serialize these into the JSON body (framework internals).
+    FRAMEWORK_IVARS = %i[
+      @event @raw_body @params @current_action @current_user_id @user_groups
+      @logger @__assigns_before @__response_status
+    ].freeze
+
+    private
+
+    # Turn the action return value (or instance-variable assigns) into an API Gateway response.
+    #
+    # Rails-like behavior for API-first controllers (default_format :json):
+    #   def index
+    #     @posts = Post.all   # → success_response({ posts: [...] })
+    #   end
+    #
+    # HTML controllers (default_format :html):
+    #   def show
+    #     @post = Post.find(...)  # → render template views/<ctrl>/show.html.erb
+    #   end
+    #
+    # Explicit responses still win:
+    #   success_response(...), error_response(...), html_response(...), render, head
+    #
+    # Non-200 with implicit body:
+    #   def create
+    #     @post = Post.create!(...)
+    #     response_status :created
+    #   end
+    def finalize_response(result)
+      return result if lambda_response?(result)
+
+      status = @__response_status || 200
+
+      return render(status: status) if self.class.default_format == :html
+
+      # Prefer assigns when present. Ruby assignment returns the RHS, so
+      # `@posts = Post.all` would otherwise look like an explicit return value.
+      # (Rails ignores the action return value entirely; we keep a thin fallback
+      # for explicit non-assign returns.)
+      assigns = collect_assigns
+      return success_response(assigns, status) if assigns.any?
+
+      return success_response({}, status) if result.nil?
+
+      success_response(serialize_for_response(result), status)
+    end
+
+    def lambda_response?(result)
+      result.is_a?(Hash) && (result.key?(:statusCode) || result.key?('statusCode'))
+    end
+
+    # Instance variables set during the action (excluding framework internals).
+    # Keys are the ivar names without @ — so @posts becomes { posts: ... }.
+    def collect_assigns
+      before = @__assigns_before || []
+      (instance_variables - before - FRAMEWORK_IVARS).each_with_object({}) do |ivar, hash|
+        key = ivar.to_s.delete_prefix('@')
+        next if key.start_with?('_')
+
+        hash[key.to_sym] = serialize_for_response(instance_variable_get(ivar))
+      end
+    end
+
+    # Deep-serialize models/relations into JSON-friendly hashes/arrays.
+    # ActiveItem::Relation (and any Enumerable of models) maps via to_h on each record.
+    def serialize_for_response(value)
+      case value
+      when nil, String, Numeric, TrueClass, FalseClass
+        value
+      when Symbol
+        value.to_s
+      when Hash
+        value.each_with_object({}) do |(k, v), h|
+          h[k.is_a?(Symbol) ? k : k.to_s] = serialize_for_response(v)
+        end
+      when Array
+        value.map { |v| serialize_for_response(v) }
+      else
+        serialize_object(value)
+      end
+    end
+
+    def serialize_object(value)
+      # Relations are Enumerable — map each record (don't call Enumerable#to_h)
+      if defined?(ActiveItem::Relation) && value.is_a?(ActiveItem::Relation)
+        value.map { |record| serialize_for_response(record) }
+      elsif value.respond_to?(:to_h) && !value.is_a?(Enumerable)
+        serialize_for_response(value.to_h)
+      elsif value.is_a?(Enumerable)
+        value.map { |item| serialize_for_response(item) }
+      elsif value.respond_to?(:to_h)
+        serialize_for_response(value.to_h)
+      else
+        value
+      end
+    end
+  end
+end

data/lib/templates/environment/backend.tf.erb

@@ -1,6 +1,6 @@
 terraform {
   backend "s3" {
-    bucket  = "belt-terraform-state"
+    bucket  = "<%= @state_bucket %>"
     key     = "<%= s3_safe_name(@app_name) %>/<%= @env_name %>/terraform.tfstate"
     region  = "us-east-1"
     encrypt = true

data/lib/templates/frontend/react/src/index.css

@@ -1,10 +1,10 @@
 :root {
-  font-family: system-ui, -apple-system, sans-serif;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
   line-height: 1.5;
-  color: #213547;
-  background-color: #ffffff;
+  color: #2d3748;
+  background-color: #f8f9fa;
 }
 
 * { box-sizing: border-box; margin: 0; padding: 0; }
 
-body { min-height: 100vh; }
+body { min-height: 100vh; background: #f8f9fa; }

data/lib/templates/frontend/react/src/lib/apiClient.js.erb

@@ -3,15 +3,32 @@ const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:3000'
 export async function apiClient(path, options = {}) {
   const { method = 'GET', body, headers = {} } = options
 
+  // Only set Content-Type when sending a body. application/json on a GET forces a
+  // CORS preflight; Accept alone is safelisted and stays a simple request.
   const config = {
     method,
-    headers: { 'Content-Type': 'application/json', ...headers }
+    headers: {
+      Accept: 'application/json',
+      ...(body !== undefined && body !== null ? { 'Content-Type': 'application/json' } : {}),
+      ...headers
+    }
   }
 
-  if (body) config.body = JSON.stringify(body)
+  if (body !== undefined && body !== null) config.body = JSON.stringify(body)
 
   const response = await fetch(`${API_URL}${path}`, config)
-  const data = await response.json()
+
+  let data
+  const text = await response.text()
+  try {
+    data = text ? JSON.parse(text) : {}
+  } catch {
+    throw new Error(
+      response.ok
+        ? 'API returned non-JSON (is VITE_API_URL pointing at the API Gateway?)'
+        : `Request failed: ${response.status}`
+    )
+  }
 
   if (!response.ok) throw new Error(data.error || `Request failed: ${response.status}`)
 

data/lib/templates/frontend/react/src/pages/Home.jsx.erb

@@ -1,9 +1,288 @@
+import { useEffect, useState } from 'react'
+import { apiClient } from '../lib/apiClient'
+
+// Mirrors lib/belt/assets/welcome.css so SPA and Lambda HTML welcome match.
+// All content lives in the hero overlay — no scroll under the poster.
+const welcomeStyles = `
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  html, body, #root { height: 100%; }
+  .belt-welcome {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #0b1220;
+    color: #2d3748;
+    min-height: 100vh;
+    height: 100%;
+    overflow: hidden;
+  }
+  .belt-welcome .hero {
+    position: relative;
+    width: 100%;
+    height: 100vh;
+    overflow: hidden;
+  }
+  .belt-welcome .hero-bg {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    /* Pin the logo / sky — crop hills at the bottom if the viewport is short */
+    object-position: top center;
+    display: block;
+  }
+  .belt-welcome .overlay {
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    padding: 1.35rem 1.6rem 1.25rem;
+    background: rgba(255, 255, 255, 0.55);
+    backdrop-filter: blur(8px);
+    -webkit-backdrop-filter: blur(8px);
+    border-radius: 14px;
+    text-align: center;
+    max-width: 560px;
+    width: min(92vw, 560px);
+    max-height: min(92vh, 620px);
+    overflow: auto;
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.18);
+  }
+  .belt-welcome .overlay h1 {
+    font-size: 1.85rem;
+    font-weight: 700;
+    color: #2d3748;
+    margin-bottom: 0.3rem;
+    line-height: 1.2;
+  }
+  .belt-welcome .overlay .subtitle {
+    font-size: 0.95rem;
+    color: #4a5568;
+    line-height: 1.4;
+  }
+  .belt-welcome .stack-check {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.4rem;
+    margin: 1rem 0 0.85rem;
+    flex-wrap: wrap;
+  }
+  .belt-welcome .check-item {
+    display: flex;
+    align-items: center;
+    gap: 0.35rem;
+    padding: 0.35rem 0.7rem;
+    border-radius: 8px;
+    font-weight: 500;
+    font-size: 0.88rem;
+  }
+  .belt-welcome .check-pass {
+    background: rgba(39, 174, 96, 0.12);
+    border: 1px solid rgba(39, 174, 96, 0.35);
+    color: #1e8449;
+  }
+  .belt-welcome .check-neutral {
+    background: rgba(113, 128, 150, 0.1);
+    border: 1px solid rgba(113, 128, 150, 0.28);
+    color: #4a5568;
+  }
+  .belt-welcome .icon { font-size: 1rem; }
+  .belt-welcome .arrow { color: #718096; font-size: 1.05rem; }
+  .belt-welcome .next-steps {
+    text-align: left;
+    border-top: 1px solid rgba(45, 55, 72, 0.12);
+    padding-top: 0.75rem;
+    margin-top: 0.15rem;
+  }
+  .belt-welcome .next-steps h2 {
+    font-size: 0.92rem;
+    margin-bottom: 0.45rem;
+    color: #2d3748;
+    text-align: left;
+  }
+  .belt-welcome .next-steps ol {
+    padding-left: 1.2rem;
+    margin: 0;
+  }
+  .belt-welcome .next-steps li {
+    margin-bottom: 0.4rem;
+    color: #4a5568;
+    line-height: 1.4;
+    font-size: 0.88rem;
+  }
+  .belt-welcome .next-steps li:last-child { margin-bottom: 0; }
+  .belt-welcome .next-steps code {
+    background: rgba(99, 45, 145, 0.1);
+    padding: 0.12rem 0.35rem;
+    border-radius: 4px;
+    color: #632d91;
+    font-size: 0.78rem;
+    word-break: break-word;
+  }
+  .belt-welcome .footer-note {
+    margin-top: 0.75rem;
+    padding-top: 0.65rem;
+    border-top: 1px solid rgba(45, 55, 72, 0.1);
+    font-size: 0.78rem;
+    color: #718096;
+    text-align: center;
+  }
+  .belt-welcome .footer-note code {
+    background: rgba(45, 55, 72, 0.06);
+    padding: 0.08rem 0.3rem;
+    border-radius: 3px;
+    color: #4a5568;
+  }
+  .belt-welcome .status-main {
+    padding: 3rem 2rem;
+    text-align: center;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    color: #4a5568;
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+  }
+  .belt-welcome .status-main h1 {
+    font-size: 1.75rem;
+    color: #2d3748;
+    margin-bottom: 0.75rem;
+  }
+  .belt-welcome .error { color: #b91c1c; margin-top: 0.75rem; }
+  .belt-welcome .muted { color: #6b7280; margin-top: 0.5rem; font-size: 0.95rem; }
+  @media (max-height: 640px) {
+    .belt-welcome .overlay { padding: 1rem 1.15rem; }
+    .belt-welcome .overlay h1 { font-size: 1.5rem; }
+    .belt-welcome .overlay .subtitle { font-size: 0.88rem; }
+    .belt-welcome .stack-check { margin: 0.7rem 0 0.55rem; }
+    .belt-welcome .check-item { padding: 0.28rem 0.55rem; font-size: 0.8rem; }
+    .belt-welcome .next-steps li { font-size: 0.82rem; }
+  }
+`
+
+function StackItem({ ok, label }) {
+  // DynamoDB false is expected (no tables yet) — neutral, not a warning.
+  const className = ok ? 'check-item check-pass' : 'check-item check-neutral'
+  return (
+    <div className={className}>
+      <span className="icon" aria-hidden="true">{ok ? '✓' : '○'}</span>
+      <span>{label}</span>
+    </div>
+  )
+}
+
+// Turn "Label: belt some command" into mixed text + <code> when possible.
+function StepLine({ step }) {
+  const match = typeof step === 'string' ? step.match(/^(.*?):\s+(belt\s.+)$/) : null
+  if (match) {
+    return (
+      <>
+        {match[1]}: <code>{match[2]}</code>
+      </>
+    )
+  }
+  return step
+}
+
 function Home() {
+  const [welcome, setWelcome] = useState(null)
+  const [error, setError] = useState(null)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    let cancelled = false
+
+    apiClient('/')
+      .then((data) => {
+        if (!cancelled) {
+          setWelcome(data)
+          setLoading(false)
+        }
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          setError(err.message || 'Failed to reach API')
+          setLoading(false)
+        }
+      })
+
+    return () => { cancelled = true }
+  }, [])
+
+  if (loading) {
+    return (
+      <div className="belt-welcome">
+        <style>{welcomeStyles}</style>
+        <main className="status-main">
+          <p className="muted">Connecting to API…</p>
+        </main>
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className="belt-welcome">
+        <style>{welcomeStyles}</style>
+        <main className="status-main">
+          <h1><%= @module_name %></h1>
+          <p className="error">Could not load welcome data from the API.</p>
+          <p className="muted">{error}</p>
+          <p className="muted" style={{ marginTop: '1rem' }}>
+            Check <code>VITE_API_URL</code> (run <code>belt frontend env dev</code>) and that CORS allows this origin.
+          </p>
+        </main>
+      </div>
+    )
+  }
+
+  const stack = welcome.stack || {}
+  const dynamoOk = !!stack.dynamodb
+  const title = welcome.title || '<%= @module_name %>'
+  const subtitle = welcome.subtitle || 'Your Belt app is running.'
+
   return (
-    <main style={{ padding: '2rem', maxWidth: '800px', margin: '0 auto' }}>
-      <h1><%= @module_name %></h1>
-      <p>Your Belt app is running. Edit <code>src/pages/Home.jsx</code> to get started.</p>
-    </main>
+    <div className="belt-welcome">
+      <style>{welcomeStyles}</style>
+
+      <div className="hero">
+        {welcome.background_image ? (
+          <img
+            src={welcome.background_image}
+            alt="Belt"
+            className="hero-bg"
+          />
+        ) : (
+          <div className="hero-bg" style={{ minHeight: '100vh', background: '#1a202c' }} />
+        )}
+        <div className="overlay">
+          <h1>{title}</h1>
+          <p className="subtitle">{subtitle}</p>
+
+          <div className="stack-check">
+            <StackItem ok={!!stack.api_gateway} label="API Gateway" />
+            <span className="arrow">→</span>
+            <StackItem ok={!!stack.lambda} label="Lambda" />
+            <span className="arrow">→</span>
+            <StackItem ok={dynamoOk} label="DynamoDB" />
+          </div>
+
+          {Array.isArray(welcome.next_steps) && welcome.next_steps.length > 0 && (
+            <div className="next-steps">
+              <h2>Next Steps</h2>
+              <ol>
+                {welcome.next_steps.map((step, i) => (
+                  <li key={i}><StepLine step={step} /></li>
+                ))}
+              </ol>
+            </div>
+          )}
+
+          <p className="footer-note">
+            Edit <code>src/pages/Home.jsx</code> to replace this page.
+          </p>
+        </div>
+      </div>
+    </div>
   )
 }
 

data/lib/templates/module/main.tf.erb

@@ -21,17 +21,27 @@ terraform {
 resource "conveyor_belt" "main" {
   provider = conveyor-belt
 
-  source            = "${path.module}/../../config/routes.tf.rb"
+  # path.module is infrastructure/modules/app — climb three levels to project root
+  source            = "${path.module}/../../../config/routes.tf.rb"
   app_name          = var.app_name
   lambda_source_dir = "${path.module}/../../../lambda"
   lambda_shared_dirs = ["controllers", "helpers", "lib", "models", "views"]
-  frontend_urls     = var.frontend_urls
+<% if @frontend -%>
+  # CloudFront first so SPA→API CORS works out of the box (tutorial footgun fixed).
+  # localhost stays via env frontend_urls for local `belt server` dev.
+  frontend_urls = concat(
+    ["https://${aws_cloudfront_distribution.frontend.domain_name}"],
+    var.frontend_urls
+  )
+<% else -%>
+  frontend_urls = var.frontend_urls
+<% end -%>
   friendly_errors   = var.environment != "prod"
 
   custom_domain_name = local.dns_enabled ? local.api_domain : ""
 
   # Per-lambda configuration from config/lambda/*.yml (database.yml style)
-  lambda_config_dir = "${path.module}/../../config/lambda"
+  lambda_config_dir = "${path.module}/../../../config/lambda"
 
   # Dynamic value references — YAML env_vars use ref(name) to pull these in
   lambda_env_refs = var.lambda_env_refs

data/lib/templates/new_app/config/routes.tf.rb.erb

@@ -1,6 +1,7 @@
 Belt.application.routes.draw do
   namespace :api do
-    get "/", action: :show, controller: :welcome
+    # Public stack-check / welcome (HTML for browsers, JSON for the SPA shell)
+    get "/", action: :show, controller: :welcome, auth: :none
     # resources :posts
   end
 end

data/lib/templates/plugin/AGENTS.md.erb

@@ -0,0 +1,135 @@
+# AGENTS.md — <%= gem_name %>
+
+This file is for AI agents (and humans) working **on this Belt plugin gem**, not on a host Belt app.
+
+Host apps get their own `AGENTS.md` from `belt new`. Core belt docs live in the [belt](https://github.com/stowzilla/belt) repo (`README.md` + root `AGENTS.md`).
+
+## What this gem is
+
+**<%= gem_name %>** is a Belt plugin: optional capability that installs into Belt apps via the generator API.
+
+- **Runtime API** lives in the gem (`<%= constant_path %>`) — apps require the gem and call it directly
+- **Generator** copies only what the host app must own (Terraform, Lambda entrypoints, optional overrides)
+- After the gem is in an app's Gemfile, `belt generate <%= plugin_name %>` / `belt destroy <%= plugin_name %>` work automatically
+
+## Stack
+
+| Piece | Role |
+|-------|------|
+| **belt** | Host framework + CLI; discovers this generator via `GeneratorRegistry` |
+| **<%= gem_name %>** (this repo) | Plugin runtime + `belt generate <%= plugin_name %>` |
+| Host Belt app | Where Terraform / Lambda config land after generation |
+
+## Layout
+
+```
+<%= gem_name %>/
+├── <%= gem_name %>.gemspec
+├── lib/
+│   ├── <%= gem_name %>.rb              # require entrypoint
+│   └── belt/
+│       ├── <%= underscored %>.rb       # <%= constant_path %> API
+│       ├── <%= underscored %>/
+│       │   ├── configuration.rb
+│       │   ├── version.rb
+│       │   └── templates/              # ERB used by the generator
+│       └── generators/
+│           └── <%= underscored %>_generator.rb   # ← auto-discovered
+├── spec/
+├── README.md
+└── AGENTS.md                           # This file
+```
+
+**Do not rename** `lib/belt/generators/<%= underscored %>_generator.rb` or the class
+`Belt::Generators::<%= generator_class %>` — discovery depends on that path and name.
+
+## Generator contract
+
+Implemented in `lib/belt/generators/<%= underscored %>_generator.rb`:
+
+| Method | Required? | Purpose |
+|--------|-----------|---------|
+| `.run(args)` | **Yes** | Install into the current Belt app |
+| `.destroy(args)` | Recommended | Tear down what generate created |
+| `.description` | Recommended | One-liner for `belt generate --help` |
+
+Class must live in `Belt::Generators` and be named `<%= generator_class %>`.
+
+Reference implementations (copy structure, don't invent a parallel one):
+
+- `belt-messaging` — SMS via AWS End User Messaging
+- `belt-pay` — Stripe payments & subscriptions
+
+## Generator checklist
+
+When fleshing out the generator, typically install:
+
+1. **Terraform module** → `infrastructure/modules/<%= plugin_name %>/` (`main.tf`, `variables.tf`, `outputs.tf`)
+2. **Lambda config** → `config/lambda/<%= plugin_name %>.yml` (timeout, memory, env, triggers)
+3. **Lambda entrypoint** → `lambda/<%= plugin_name %>.rb` using `Belt::LambdaHandler`
+4. **Routes / schema** → inject into `config/routes.tf.rb` or schema files when needed
+5. **Optional overrides** → `--controllers` (or similar) for app-local subclasses — keep defaults in the gem
+6. **Destroy path** → `belt destroy <%= plugin_name %>` removes generated artifacts
+7. **Help** → `.description` plus `--help` / `-h` explaining files and next steps
+
+**Principle:** runtime stays in the gem; generators copy only host-owned infra and optional overrides (same idea as `rails g devise:views`).
+
+## Local development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+Wire into a Belt app while iterating:
+
+```ruby
+# In the app Gemfile
+gem "<%= gem_name %>", path: "../<%= gem_name %>"
+```
+
+```bash
+cd /path/to/belt-app
+bundle install
+belt generate --help          # should list "<%= plugin_name %>" under Gem Generators
+belt generate <%= plugin_name %>
+belt destroy <%= plugin_name %>
+```
+
+`belt deploy` vendors `path:` gems into `vendor/cache` so Lambda packaging works without publishing.
+
+## Configuration pattern
+
+```ruby
+<%= constant_path %>.configure do |config|
+  # config.option = value
+end
+```
+
+Extend `lib/belt/<%= underscored %>/configuration.rb` and document options in README.
+
+## Conventions
+
+1. Follow patterns from `belt-messaging` / `belt-pay` before inventing new structure
+2. Keep the generator idempotent where practical; support `--force` for overwrites
+3. Specs under `spec/` for configuration and any non-trivial generator logic
+4. User-facing changes → `CHANGELOG.md`
+5. Never commit secrets, API keys, or real AWS account IDs
+6. Prefer gem defaults + optional generate flags over dumping all code into the app
+
+## Where to look first
+
+| Task | Start here |
+|------|------------|
+| Runtime API | `lib/belt/<%= underscored %>.rb`, `lib/belt/<%= underscored %>/` |
+| What gets installed into apps | `lib/belt/generators/<%= underscored %>_generator.rb` |
+| Generator ERB templates | `lib/belt/<%= underscored %>/templates/` |
+| Version / gemspec | `lib/belt/<%= underscored %>/version.rb`, `<%= gem_name %>.gemspec` |
+| How belt discovers this | belt gem: `Belt::CLI::GeneratorRegistry` |
+
+## Do not
+
+- Move the generator file out of `lib/belt/generators/*_generator.rb`
+- Require a manual initializer in the host app for registration — discovery is automatic
+- Put host-app deploy runbooks here — those belong in the app's `AGENTS.md`
+- Duplicate large runtime classes into generated app files unless the user opts in (e.g. `--controllers`)

data/lib/templates/plugin/CHANGELOG.md.erb

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1
+
+- Initial scaffold generated by `belt plugin new <%= plugin_name %>`