iron-cms 0.17.2 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7441460ff6c611510525a11808f5fe2deb724574380f91b5ffab5edbb1c571a0
-  data.tar.gz: 157944fd97ba5e0b6aba79409fd0b456bd6bef4cb802ed836eba2dc9b693de15
+  metadata.gz: fdbdcd75d63988db324f7cd3520ff66b7327aa366a8316e82ca0a48fc02f5830
+  data.tar.gz: 55f750ec5c956ea41834df8c10fec16aa12e99e01224ab6c9fc142f2c76843d0
 SHA512:
-  metadata.gz: 5fd0f51df8afd88331e30b3349eee6e1dfb6df988ab1f17b5a5362d2e94f71d6fbabfb2e62001c8627c6e2a2c5c0a0ad998c4ae9b192319b6cf37d392ef13fe2
-  data.tar.gz: a6a1b3169c158dae96b9190b0553b0e83eaf450df510cefcc70915aca31087284d495fc28269c271a9827f3a59f2d04cca87657b00e22e0e392cd3eedbec8ae7
+  metadata.gz: 0b5f6d0e3e5c7114cea52af8687af60ef66afd906025c5fc4a394fa6c5a3ecdbc029117028a1c938c6f02fe6e9a4530083cf36c281e2b37723395604e7aea274
+  data.tar.gz: 9437328b4b67b083d7c57938acfcb8b5f5d7a082e831b21890eff4afd2c3dc2b051dadb1b0def5eaa26b5192fbc8aadff9f1cc60e5fafc99b79033a63ca57eac

data/README.md

@@ -35,7 +35,7 @@ Iron CMS allows you to publish content types to your website. To set this up:
 
 4. **Access your content** on the web:
    - Entries will be available at their generated routes
-   - Use the `iron_entry_path(@entry)` helper to generate URLs
+   - Use the `iron_entry_path(@entry.attributes)` helper to generate URLs
    - Multi-locale support is built-in with URL prefixes
 
 ### Responsive Images
@@ -127,6 +127,40 @@ The seed creates a default admin user during loading. Configure via environment
 - `IRON_SEED_EMAIL` (default: `admin@example.com`)
 - `IRON_SEED_PASSWORD` (default: `password`)
 
+### Building with AI Agents
+
+Iron is built for agent-driven development: the CMS schema lives in a declarative file and content is managed through rake tasks, so a coding agent can take a site from brief to working CMS without clicking through the admin.
+
+Install the knowledge package:
+
+```bash
+bin/rails g iron:agents
+```
+
+This creates `.claude/skills/iron-cms/SKILL.md` — a Claude Code skill teaching agents the full workflow (schema file format, field types, payload formats) — and adds an `## Iron CMS` command crib sheet to your `AGENTS.md` (created if missing).
+
+The schema lives in `db/cms/schema.json` and declares locales, block definitions and content types:
+
+```bash
+bin/rails iron:schema:dump    # write the current schema to db/cms/schema.json
+bin/rails iron:schema:diff    # preview what apply would change
+bin/rails iron:schema:apply   # upsert the file into the database (PRUNE=1 also deletes)
+```
+
+Apply upserts by handle and is additive by default. In development, schema edits made in the admin UI are dumped back to the file automatically, so it stays current either way.
+
+Content is managed imperatively:
+
+```bash
+bin/rails iron:content:list HANDLE=post
+bin/rails iron:content:get HANDLE=post ROUTE=hello-world
+bin/rails iron:content:create HANDLE=post PAYLOAD='{"title": "Hello"}'
+bin/rails iron:content:update HANDLE=post ID=12 PAYLOAD='{"title": "Hi"}'
+bin/rails iron:content:delete HANDLE=post ID=12
+```
+
+Payloads are JSON objects of field handles to values — inline via `PAYLOAD=`, from a file via `FILE=`, or piped on stdin. Results print as JSON on stdout; validation errors as JSON on stderr. See the generated skill for payload semantics per field type, file ingestion, and the end-to-end loop.
+
 ## System Requirements
 
 Iron requires `libvips` to be installed on your system for image processing and responsive image generation.
@@ -150,7 +184,52 @@ sudo pacman -S libvips
 
 ## Installation
 
-Add this line to your application's Gemfile:
+### Quickstart
+
+Create a new Iron-powered site in two commands:
+
+```bash
+gem install iron-cms
+iron new mysite
+```
+
+`iron new` scaffolds a fresh Rails app and runs `rails g iron:install` to wire Iron in. Then start it:
+
+```bash
+cd mysite
+bin/dev   # open http://localhost:3000/admin
+```
+
+When developing Iron itself, point the new app at a local checkout with `iron new mysite --path /path/to/iron`.
+
+For an **existing** Rails app, add the gem and run the generator directly:
+
+```bash
+bundle add iron-cms
+bin/rails g iron:install
+```
+
+`rails g iron:install` wires everything up and is safe to re-run:
+
+- mounts `Iron::Engine` at `/admin`
+- installs the Active Storage, Action Text, and Iron migrations
+- drops a minimal `db/cms/schema.json` skeleton for the schema-as-code workflow
+- appends an idempotent administrator-provisioning block to `db/seeds.rb` (the SKILL.md seed-zip workflow adds `Iron::Seed.load` below this block rather than re-provisioning the admin)
+- emits `lib/tasks/iron_release.rake` so `db:prepare` also runs `iron:schema:apply`
+- installs the `iron-cms` agent skill (`rails g iron:agents`) and the pages controller (`rails g iron:pages`)
+- runs `db:prepare` then `db:seed` (migrate, apply the schema, and provision the first admin)
+
+Provisioning credentials come from `IRON_SEED_EMAIL` / `IRON_SEED_PASSWORD` (defaulting to `admin@example.com` / `password` in local environments — development and test; **required in any non-local environment** like staging or production, where seeding fails fast without them).
+
+The local agent workflow drives Iron through the `iron:schema` / `iron:content` rake tasks and needs no API token. If you later want to reach the REST API over HTTP, mint one explicitly with `bin/rails iron:integration:create NAME=agent ROLE=administrator` (it's shown once).
+
+Because `db:prepare` now also applies the CMS schema, `bin/kamal deploy` converges migrations and the CMS schema on every deploy — its Docker entrypoint runs `db:prepare`, so no deploy-specific wiring is needed. The hook works under any deploy mechanism that runs `db:prepare`.
+
+The `iron-cms` agent skill and an `## Iron CMS` section in `AGENTS.md` are now installed: open the new app in Claude Code and hand it a content brief — it will model `db/cms/schema.json`, apply it, and populate content using the `iron:schema` / `iron:content` tasks.
+
+### Manual installation
+
+If you prefer to wire Iron up by hand, add this line to your application's Gemfile:
 
 ```ruby
 gem "iron-cms"
@@ -165,15 +244,20 @@ bundle
 Or install it yourself as:
 
 ```bash
-gem install iron
+gem install iron-cms
 ```
 
-Then copy iron migrations:
+Iron stores file uploads with Active Storage and rich text with Action Text. If your application doesn't have their tables yet, install them first, then copy the Iron migrations and migrate:
 
 ```bash
+bin/rails active_storage:install
+bin/rails action_text:install:migrations
 bin/rails iron:install:migrations
+bin/rails db:migrate
 ```
 
+(`action_text:install:migrations` copies just the table migration — Iron ships its own editor, so the full Action Text JavaScript setup isn't needed.)
+
 Configure the mailer sender address used for system emails (e.g. password resets):
 
 ```ruby