iron-cms 0.17.2 → 0.18.0

data/lib/generators/iron/agents/templates/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: iron-cms
+description: Build and manage CMS-driven Rails sites with Iron CMS. Use when modeling content types, editing db/cms/schema.json, creating or editing CMS content, or building site templates.
+---
+
+# Iron CMS
+
+Iron is a Rails engine CMS. The content model (content types, block definitions, fields,
+locales) lives declaratively in `db/cms/schema.json`. Content (entries) lives in the
+database and is managed through `iron:content:*` rake tasks. All commands below run from
+the host app root.
+
+## The loop
+
+Build a site by repeating this cycle:
+
+1. Model content in `db/cms/schema.json` (write it by hand on a fresh app, or run
+   `bin/rails iron:schema:dump` to materialize the current database schema).
+2. `bin/rails iron:schema:diff` — self-check what apply would change.
+3. `bin/rails iron:schema:apply` — upsert the schema into the database.
+4. Scaffold templates: `bin/rails g iron:pages` (once per app), then
+   `bin/rails g iron:template <handle>` for each web-published content type.
+5. Populate content with `bin/rails iron:content:create` / `iron:content:update`.
+6. Verify in the browser (`bin/dev`).
+7. Checkpoint: `bin/rails iron:seed:dump`, then commit `db/cms/schema.json` and
+   `db/seeds/iron.zip`.
+
+## Schema file reference
+
+A complete `db/cms/schema.json`:
+
+```json
+{
+  "version": "1.0",
+  "default_locale": "en",
+  "locales": [
+    { "code": "en", "name": "English" }
+  ],
+  "block_definitions": [
+    {
+      "handle": "hero_section",
+      "name": "Hero Section",
+      "field_definitions": [
+        { "handle": "title", "name": "Title", "type": "text_field", "metadata": { "required": true } },
+        { "handle": "subtitle", "name": "Subtitle", "type": "text_area" },
+        {
+          "handle": "image",
+          "name": "Image",
+          "type": "file",
+          "metadata": { "file_scope": "specific", "selected_presets": ["images"] }
+        }
+      ]
+    },
+    {
+      "handle": "quote_section",
+      "name": "Quote Section",
+      "field_definitions": [
+        { "handle": "quote", "name": "Quote", "type": "text_area" },
+        { "handle": "attribution", "name": "Attribution", "type": "text_field" }
+      ]
+    },
+    {
+      "handle": "seo",
+      "name": "SEO",
+      "field_definitions": [
+        { "handle": "title", "name": "SEO Title", "type": "text_field" },
+        { "handle": "description", "name": "SEO Description", "type": "text_area" }
+      ]
+    }
+  ],
+  "content_types": [
+    {
+      "handle": "author",
+      "name": "Author",
+      "type": "collection",
+      "icon": "user",
+      "title_field_handle": "name",
+      "field_definitions": [
+        { "handle": "name", "name": "Name", "type": "text_field", "metadata": { "required": true } },
+        { "handle": "bio", "name": "Bio", "type": "text_area" },
+        {
+          "handle": "photo",
+          "name": "Photo",
+          "type": "file",
+          "metadata": { "file_scope": "specific", "selected_presets": ["images"] }
+        }
+      ]
+    },
+    {
+      "handle": "page",
+      "name": "Page",
+      "type": "single",
+      "icon": "panels-top-left",
+      "web_publishing_enabled": true,
+      "title_field_handle": "title",
+      "web_page_title_field_handle": "title",
+      "field_definitions": [
+        { "handle": "title", "name": "Title", "type": "text_field", "metadata": { "required": true, "searchable": true } },
+        {
+          "handle": "sections",
+          "name": "Sections",
+          "type": "block_list",
+          "supported_block_definitions": ["hero_section", "quote_section"]
+        },
+        {
+          "handle": "seo",
+          "name": "SEO",
+          "type": "block",
+          "supported_block_definitions": ["seo"]
+        }
+      ]
+    },
+    {
+      "handle": "post",
+      "name": "Post",
+      "type": "collection",
+      "icon": "newspaper",
+      "web_publishing_enabled": true,
+      "base_path": "blog",
+      "title_field_handle": "title",
+      "web_page_title_field_handle": "title",
+      "field_definitions": [
+        { "handle": "title", "name": "Title", "type": "text_field", "metadata": { "required": true, "max_length": 120, "searchable": true } },
+        { "handle": "status", "name": "Status", "type": "text_field", "metadata": { "required": true, "allowed_values": ["draft", "published"] } },
+        { "handle": "body", "name": "Body", "type": "rich_text_area", "metadata": { "searchable": true } },
+        { "handle": "published_on", "name": "Published On", "type": "date" },
+        { "handle": "featured", "name": "Featured", "type": "boolean" },
+        {
+          "handle": "cover",
+          "name": "Cover",
+          "type": "file",
+          "metadata": { "file_scope": "specific", "selected_presets": ["images"] }
+        },
+        { "handle": "author", "name": "Author", "type": "reference", "supported_content_types": ["author"] },
+        { "handle": "related_posts", "name": "Related Posts", "type": "reference_list", "supported_content_types": ["post"] }
+      ]
+    }
+  ]
+}
+```
+
+Top-level keys: `version` (always `"1.0"`), `default_locale` (one of the locale codes),
+`locales` (each `code` + `name`), `block_definitions`, `content_types`.
+
+### Content type attributes
+
+- `handle` (required) — identifier used everywhere: tasks, templates, API.
+- `name` (required) — display name in the admin.
+- `type` (required) — `"single"` (exactly one entry: homepage, settings) or
+  `"collection"` (many entries: posts, projects).
+- `description` — optional, shown in the admin.
+- `icon` — **always pick one**; it identifies the type in the admin sidebar. Names come
+  from the Lucide icon set and `iron:schema:apply` rejects unknown ones. Good picks:
+  `file-text`, `files`, `newspaper`, `notebook-text`, `panels-top-left`,
+  `layout-template`, `image`, `images`, `calendar`, `user`, `users`, `tag`, `folder`,
+  `shopping-bag`, `package`, `map-pin`, `phone`, `mail`, `star`, `trophy`, `megaphone`,
+  `briefcase`, `building-2`, `book-open`, `message-square`, `circle-help`, `list`,
+  `layers`, `globe`, `video`, `music`, `camera`, `utensils`, `dumbbell`,
+  `graduation-cap`, `car`, `palette`, `quote`. (Full set:
+  `bin/rails runner "puts Iron::IconCatalog.all"`.)
+- `web_publishing_enabled` — entries get public routes (omit for false).
+- `base_path` — URL prefix for those routes (`"blog"` → `/blog/my-post`).
+- `title_field_handle` — handle of the field naming entries in the admin and search.
+- `web_page_title_field_handle` — handle of the field used as the web page title and
+  for route generation.
+- `field_definitions` — array of fields; array order is the display order.
+
+### Field types
+
+A field definition has `handle`, `name`, `type`, an optional `metadata` object holding
+the per-type configuration (validation rules plus flags like `searchable`), and — for
+block/reference types — a top-level `supported_block_definitions` or
+`supported_content_types` array (these are siblings of `metadata`, not inside it).
+
+| `type` | Content payload value | Validations (`metadata` keys) | Other `metadata` / extra keys |
+| --- | --- | --- | --- |
+| `text_field` | string | `required`, `allowed_values` (non-empty array of distinct strings), `min_length` / `max_length` (integers >= 1) | `searchable` |
+| `text_area` | string | `required`, `min_length` / `max_length` | `searchable` |
+| `rich_text_area` | HTML string | `required` | `searchable` |
+| `number` | number | `required`, `min` / `max` (numbers) | — |
+| `boolean` | `true` / `false` | — | — |
+| `date` | ISO 8601 date or datetime string (`"2026-06-11"`) | `required` | — |
+| `file` | `{ "_file": "<path or URL>" }` | `required`, `file_scope` (`"all"` default, or `"specific"`), `selected_presets` (with `"specific"`: non-empty array drawn from `images`, `videos`, `documents`, `audio`) | — |
+| `reference` | entry id (integer) | `required` | `supported_content_types` (content type handles) |
+| `reference_list` | array of entry ids | — | `supported_content_types` |
+| `block` | object of nested field handles | — | `supported_block_definitions` (exactly one handle) |
+| `block_list` | array of objects, each with `"_type": "<block_definition_handle>"` | — | `supported_block_definitions` (one or more handles) |
+
+Validations are enforced on every write surface (admin form, `iron:content:*` tasks,
+HTTP content API). A rejected write reports field-keyed errors — the CLI prints on
+stderr:
+
+```json
+{ "errors": { "status": ["must be one of: draft, published"], "sections[0].title": ["can't be blank"] } }
+```
+
+(the HTTP API returns the same flat hash without the `errors` wrapper). The messages
+embed the allowed values and bounds needed to fix the payload.
+
+### Rules
+
+- **Array order is display order.** There are no rank keys — reorder fields by
+  reordering the array.
+- **Validation rules are plain `metadata` keys.** An omitted key means no constraint,
+  and on apply the file is authoritative: omitting a key clears a previously applied
+  rule. Unknown or inapplicable keys are rejected upfront by `iron:schema:apply`.
+- **Omitted booleans are false.** Only write `web_publishing_enabled`, `required`,
+  `searchable`, etc. when true.
+- **Handles are lowercase snake_case** (`a-z`, `0-9`, `_`). Reserved handles: `id`,
+  `base`, `_metadata`, `_type`.
+- **Renaming a handle is a delete + create.** The old object stays in the database
+  until you apply with `PRUNE=1`, which destroys it along with its stored data.
+- **Changing a field's `type` discards its stored values** — the old values are
+  unusable under the new type.
+- `supported_block_definitions` / `supported_content_types` handles must exist in this
+  file (or already in the database — but with `PRUNE=1` only handles kept by the file
+  count, since everything else is destroyed).
+
+## Modeling playbook
+
+- **Single vs collection**: use a single for one-off pages and global settings
+  (homepage, footer, site settings); a collection for repeatable content (posts,
+  projects, people).
+- **Page builder**: define reusable sections as block definitions and give the page a
+  `block_list` field supporting them. Editors compose pages; templates switch on
+  `_type`.
+- **Fixed structured groups** (an SEO panel, a CTA): a `block` field with exactly one
+  supported block definition.
+- **Relations**: `reference` for one (post → author), `reference_list` for many.
+- **Always set `title_field_handle`** to a text_field — it names entries in the admin
+  and powers search.
+- **Web publishing**: `web_publishing_enabled: true` gives entries public routes,
+  auto-generated by parameterizing the web page title (set
+  `web_page_title_field_handle`). `base_path` nests them. An entry with the empty
+  route `""` serves the site index `/`.
+
+## Schema commands
+
+```bash
+bin/rails iron:schema:dump    # write the current database schema to db/cms/schema.json
+bin/rails iron:schema:diff    # show drift between file and database, both directions
+bin/rails iron:schema:apply   # upsert the file into the database
+```
+
+Options (ENV vars):
+
+- `SCHEMA_PATH=path/to/schema.json` — alternate file, all three tasks.
+- `PRUNE=1` — apply only: ALSO destroy database objects missing from the file.
+  Destroying a content type cascades to all its entries; destroying a field
+  definition destroys its stored values. Without `PRUNE`, apply is additive and
+  updating: objects in the file are upserted by handle, database-only objects are
+  left alone (diff still lists them as removal candidates).
+- `FORMAT=json` — machine-readable output.
+
+Apply is idempotent — applying an unchanged file reports "Schema is in sync." Apply
+also bootstraps a fresh database (no prior setup needed). In development, schema
+changes made through the admin UI are automatically dumped back to
+`db/cms/schema.json` (as long as the file exists), so file edits and UI edits mix
+safely.
+
+## Content commands
+
+```bash
+bin/rails iron:content:list   HANDLE=post
+bin/rails iron:content:get    HANDLE=post ID=12          # or ROUTE=hello-world
+bin/rails iron:content:create HANDLE=post ROUTE=hello-world
+bin/rails iron:content:update HANDLE=post ID=12
+bin/rails iron:content:delete HANDLE=post ID=12          # or ROUTE=hello-world
+```
+
+The contract:
+
+- `HANDLE=` is always required. An unknown handle aborts with the list of known
+  handles.
+- For create/update, the payload is a JSON object of field handles → values (see the
+  field type table). Provide it inline with `PAYLOAD='{...}'`, from a file with
+  `FILE=payload.json`, or pipe it on stdin (heredoc — best for multi-line payloads).
+- `ROUTE=` is not a content field: it identifies an entry (get/update/delete) or sets
+  the route at create time. Omit it to let Iron generate the route from the web page
+  title.
+- `LOCALE=it` reads or writes the given locale; omitted, the account default locale
+  is used.
+- Success prints the entry as pretty JSON on stdout (field values plus a `_metadata`
+  object with `content_type`, `locale`, `title`, `route`, `path`, timestamps) and
+  exits 0.
+- **The printed entry is read-only output, not a resubmittable payload**: file fields
+  print as `{url, filename, ...}` objects and references print expanded — when
+  sending values back, rewrite them as `{"_file": ...}`, an entry id, or an array of
+  ids per the field type table.
+- Validation failure prints `{"errors": {...}}` on stderr and exits 1. Error keys are
+  dotted/indexed field paths, e.g. `{"errors": {"sections[0].title": ["can't be blank"]}}`.
+- Content writes are attributed to a dedicated System user, created automatically
+  on first use — no pre-existing user is required.
+
+### Create
+
+```bash
+bin/rails iron:content:create HANDLE=post ROUTE=hello-world <<'JSON'
+{
+  "title": "Hello World",
+  "status": "published",
+  "body": "<p>Our <strong>first</strong> post.</p>",
+  "published_on": "2026-06-11",
+  "featured": true,
+  "cover": { "_file": "app/assets/images/hello.jpg" },
+  "author": 3,
+  "related_posts": [4, 7]
+}
+JSON
+```
+
+Short payloads inline:
+
+```bash
+bin/rails iron:content:create HANDLE=author PAYLOAD='{"name": "Ada Lorne"}'
+```
+
+### Files
+
+Wherever a file field expects a value, pass `{ "_file": "<source>" }` — a file path
+(absolute or relative to the app root) or an `http(s)://` URL. The file is downloaded
+if remote, uploaded to Active Storage, and attached.
+
+### Blocks and block lists
+
+Block list items each require a `"_type"` naming the block definition; a `block`
+field takes a plain object. Both replace their previous value wholesale:
+
+```bash
+bin/rails iron:content:update HANDLE=page <<'JSON'
+{
+  "title": "Home",
+  "sections": [
+    { "_type": "hero_section", "title": "Welcome", "image": { "_file": "https://example.com/hero.jpg" } },
+    { "_type": "quote_section", "quote": "Make it iron-clad.", "attribution": "Ada Lorne" }
+  ],
+  "seo": { "title": "Home", "description": "Welcome to our site." }
+}
+JSON
+```
+
+### Update
+
+Updates are partial: omitted fields are untouched, an explicit `null` clears a field.
+`reference_list`, `block`, and `block_list` values replace the whole previous value —
+send the complete new value.
+
+```bash
+bin/rails iron:content:update HANDLE=post ID=12 PAYLOAD='{"featured": false}'
+```
+
+Singles upsert through update — no `ID`/`ROUTE`, and the entry is created on first
+run (`iron:content:create` on a single is an error). The same id-less form fetches
+it: `bin/rails iron:content:get HANDLE=page`.
+
+### Locales
+
+```bash
+bin/rails iron:content:update HANDLE=page LOCALE=it PAYLOAD='{"title": "Casa"}'
+bin/rails iron:content:get HANDLE=page LOCALE=it
+```
+
+### Delete
+
+```bash
+bin/rails iron:content:delete HANDLE=post ID=12
+```
+
+Prints `{"deleted": true, "id": 12}`.
+
+## Templates & rendering
+
+```bash
+bin/rails g iron:pages          # once: PagesController + iron_pages route + default view
+bin/rails g iron:template post  # per content type — run AFTER iron:schema:apply (reads the DB)
+```
+
+Each web-published content type renders `app/views/templates/<handle>.html.erb`
+(falling back to the generated `app/views/pages/show.html.erb`). Entry data is
+exposed through `@entry.attributes`:
+
+```erb
+<h1><%= @entry.attributes.title %></h1>
+<%= raw @entry.attributes.body %>
+
+<% @entry.attributes.sections.each do |section| %>
+  <% case section._type %>
+  <% when "hero_section" %>
+    <h2><%= section.title %></h2>
+    <%= iron_picture_tag section.image %>
+  <% when "quote_section" %>
+    <blockquote><%= section.quote %> — <%= section.attribution %></blockquote>
+  <% end %>
+<% end %>
+```
+
+- File fields return the attachment (or nil). Render images with `iron_picture_tag`
+  (responsive `<picture>` with AVIF/WebP variants) or `iron_image_tag`; include
+  `Iron::ImageHelper` in your `ApplicationHelper` first.
+- Reference fields return a stub with `.id` and `._type`; load the entry for its
+  content: `Iron::Entry.find(@entry.attributes.author.id).attributes.name`.
+- Link to web-published entries with `iron_entry_path(entry.attributes)` — note it
+  takes the presented attributes, not the record. The current page's path and title
+  live at `@entry.attributes._metadata.web.path` / `.title`.
+- URLs for non-default locales are prefixed with the locale code (`/it/...`).
+
+## Checkpoint & deploy
+
+- `bin/rails iron:seed:dump` exports the full CMS state (schema + entries + files) to
+  `db/seeds/iron.zip`. Commit it together with `db/cms/schema.json` after each
+  working increment.
+- Add `Iron::Seed.load` to `db/seeds.rb`: `rails db:prepare` then bootstraps an empty
+  database (skipped when content types already exist). If `iron:install` already wrote
+  an `# == Iron CMS admin ==` block, append `Iron::Seed.load` below it rather than
+  re-adding admin provisioning — both read the same credentials. Configure with
+  `IRON_SEED_EMAIL` / `IRON_SEED_PASSWORD` (defaults `admin@example.com` / `password`
+  in local environments; both required outside them).
+- To drive a remote instance over HTTP instead of rake: create a token with
+  `bin/rails iron:integration:create NAME=agent ROLE=member` (roles `reader`,
+  `member`, `administrator`; the token is shown once), send it as
+  `Authorization: Bearer <token>`, and fetch the OpenAPI spec at
+  `<iron mount path>/api/openapi.json` (e.g. `/admin/api/openapi.json` when the engine
+  is mounted at `/admin`) for the full HTTP content API.

data/lib/generators/iron/install/install_generator.rb

@@ -0,0 +1,118 @@
+require "rails/generators"
+
+module Iron
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      MOUNT_PATH = "/admin".freeze
+      MOUNT_LINE = %(mount Iron::Engine => "#{MOUNT_PATH}").freeze
+      SEEDS_MARKER = "# == Iron CMS admin ==".freeze
+
+      class_option :skip_db, type: :boolean, default: false,
+        desc: "Skip the database steps (migrate, seed, schema apply)"
+
+      def mount_engine
+        route MOUNT_LINE unless routes_include?(MOUNT_LINE)
+      end
+
+      def install_active_storage
+        return if skip_db_steps?
+        return if migration_present?("create_active_storage_tables.active_storage.rb")
+
+        rails_command "active_storage:install", inline: true
+      end
+
+      def install_action_text
+        return if skip_db_steps?
+        return if migration_present?("create_action_text_tables.action_text.rb")
+
+        rails_command "action_text:install:migrations", inline: true
+      end
+
+      def install_iron_migrations
+        return if skip_db_steps?
+
+        rails_command "iron:install:migrations", inline: true
+      end
+
+      def create_schema_skeleton
+        copy_file "schema.json", "db/cms/schema.json"
+      end
+
+      def create_seeds
+        return if seeds_marker_present?
+
+        if File.exist?(seeds_path)
+          append_to_file "db/seeds.rb", seeds_block
+        else
+          copy_file "seeds.rb", "db/seeds.rb"
+        end
+      end
+
+      def wire_release_step
+        copy_file "iron_release.rake", "lib/tasks/iron_release.rake"
+      end
+
+      def install_agent_skill
+        invoke "iron:agents", [], quiet: true
+      end
+
+      def install_pages
+        invoke "iron:pages", [], quiet: true unless routes_include?("iron_pages")
+      end
+
+      def provision_admin
+        return if skip_db_steps?
+
+        rails_command "db:prepare", abort_on_failure: true
+        rails_command "db:seed", abort_on_failure: true
+      end
+
+      def display_instructions
+        say "\n=== Iron CMS Installed ===\n", :green
+        say "Created:"
+        say "  - config/routes.rb mounts Iron::Engine at #{MOUNT_PATH}"
+        say "  - db/cms/schema.json (minimal CMS schema skeleton — edit, then bin/rails iron:schema:apply)"
+        say "  - db/seeds.rb provisions the first administrator (run by db:seed)"
+        say "  - lib/tasks/iron_release.rake applies the CMS schema during db:prepare"
+        say "  - .claude/skills/iron-cms/SKILL.md (the Iron CMS workflow for coding agents)"
+        say "  - app/controllers/pages_controller.rb renders published content"
+        say "\nSet IRON_SEED_EMAIL and IRON_SEED_PASSWORD outside local environments, or seeding fails fast."
+        say "\nNext steps:"
+        say "1. Run bin/dev and open http://localhost:3000#{MOUNT_PATH} to sign in."
+        say "2. Deploy with bin/kamal deploy — db:prepare migrates and applies the CMS schema."
+      end
+
+      private
+
+        def skip_db_steps?
+          options[:skip_db] || options[:pretend]
+        end
+
+        def routes_path
+          File.join(destination_root, "config", "routes.rb")
+        end
+
+        def routes_include?(line)
+          File.exist?(routes_path) && File.read(routes_path).include?(line)
+        end
+
+        def seeds_path
+          File.join(destination_root, "db", "seeds.rb")
+        end
+
+        def seeds_marker_present?
+          File.exist?(seeds_path) && File.read(seeds_path).include?(SEEDS_MARKER)
+        end
+
+        def seeds_block
+          "\n#{File.read(find_in_source_paths("seeds.rb"))}"
+        end
+
+        def migration_present?(suffix)
+          Dir.glob(File.join(destination_root, "db", "migrate", "*_#{suffix}")).any?
+        end
+    end
+  end
+end

data/lib/generators/iron/install/templates/iron_release.rake

@@ -0,0 +1,5 @@
+if Rake::Task.task_defined?("db:prepare")
+  Rake::Task["db:prepare"].enhance do
+    Rake::Task["iron:schema:apply"].invoke
+  end
+end

data/lib/generators/iron/install/templates/schema.json

@@ -0,0 +1,12 @@
+{
+  "version": "1.0",
+  "default_locale": "en",
+  "locales": [
+    {
+      "code": "en",
+      "name": "English"
+    }
+  ],
+  "block_definitions": [],
+  "content_types": []
+}

data/lib/generators/iron/install/templates/seeds.rb

@@ -0,0 +1,13 @@
+# == Iron CMS admin ==
+def iron_seed_credential(env_key, fallback)
+  ENV.fetch(env_key) do
+    Rails.env.local? ? fallback : raise("#{env_key} is required outside local environments")
+  end
+end
+
+if Iron::User.people.none?
+  Iron::FirstRun.create!(
+    email_address: iron_seed_credential("IRON_SEED_EMAIL", "admin@example.com"),
+    password: iron_seed_credential("IRON_SEED_PASSWORD", "password")
+  )
+end

data/lib/generators/iron/pages/pages_generator.rb

@@ -5,6 +5,9 @@ module Iron
     class PagesGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
+      class_option :quiet, type: :boolean, default: false,
+        desc: "Suppress the closing instructions (set when composed by iron:install)"
+
       def create_controller
         template "pages_controller.rb", "app/controllers/pages_controller.rb"
       end
@@ -18,6 +21,8 @@ module Iron
       end
 
       def display_instructions
+        return if options[:quiet]
+
         say "\n=== Iron CMS Pages Setup Complete ===\n", :green
         say "The pages controller has been installed in your application.\n"
         say "\nNext steps:"

data/lib/generators/iron/pages/templates/pages_controller.rb

@@ -3,7 +3,7 @@ class PagesController < ApplicationController
 
   def show
     @content_type = Iron::ContentType.web_published.find_by_handle!(params[:content_type])
-    @entry = Iron::SDK.send(@content_type.handle).find(params[:route])
+    @entry = @content_type.entries.find_by(route: params[:route])
 
     raise ActiveRecord::RecordNotFound unless @entry
 

data/lib/generators/iron/pages/templates/show.html.erb

@@ -1,4 +1,4 @@
-<h1><%%= @entry._metadata.web.title %></h1>
+<h1><%%= @entry.attributes._metadata.web.title %></h1>
 
 <hr>
 

data/lib/install/template.rb

@@ -0,0 +1,9 @@
+if (iron_path = ENV["IRON_GEM_PATH"])
+  gem "iron-cms", path: iron_path
+else
+  gem "iron-cms"
+end
+
+after_bundle do
+  generate "iron:install"
+end

data/lib/iron/cli.rb

@@ -0,0 +1,43 @@
+require "thor"
+require "bundler"
+
+module Iron
+  class CLI < Thor
+    def self.exit_on_failure? = true
+
+    desc "new APP_PATH", "Create a new Rails application with Iron CMS installed"
+    long_desc <<~DESC
+      Scaffolds a fresh Rails application and wires in Iron CMS — mounting the engine,
+      installing migrations, dropping a schema skeleton, provisioning the first
+      administrator, and installing the agent skill.
+
+      Uses the released iron-cms gem. Pass --path to pin the new app to a local
+      checkout while developing the gem itself.
+    DESC
+    method_option :path, type: :string, aliases: "-p",
+      desc: "Pin the new app to a local Iron checkout instead of the released gem"
+    def new(app_path)
+      scaffold app_path, local_checkout: options[:path]
+    end
+
+    desc "version", "Print the Iron CMS version"
+    def version
+      require "iron/version"
+      say Iron::VERSION
+    end
+    map %w[-v --version] => :version
+
+    private
+      def scaffold(app_path, local_checkout:)
+        env = local_checkout ? { "IRON_GEM_PATH" => File.expand_path(local_checkout) } : {}
+        command = [ "rails", "new", app_path, "-m", template_path ]
+
+        scaffolded = Bundler.with_unbundled_env { Kernel.system(env, *command) }
+        abort "`rails new` failed — make sure Rails is installed (gem install rails)." unless scaffolded
+      end
+
+      def template_path
+        File.expand_path("../install/template.rb", __dir__)
+      end
+  end
+end

data/lib/iron/version.rb

@@ -1,3 +1,3 @@
 module Iron
-  VERSION = "0.17.2"
+  VERSION = "0.18.0"
 end