open_blog 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dc9141447562952baf038f0a5a46bd4d6f300d7fd86d2f87f621ac4103ab22b
-  data.tar.gz: bed8bf059533885de53c23f62ba7de2166f4b529846ef53614dc1d0d90740e4d
+  metadata.gz: 0473f44b17fe66c2fc03de0c142fa17bf8b139047b6b8ba1d5d9aff5bfe41a93
+  data.tar.gz: 5108c7a099c89c3353499bb2f719bc2e8fa67c9530cf34544e1fc0df11f79deb
 SHA512:
-  metadata.gz: '08b3286b42ed0b5ed9ab2879946d7fb122743732b51f5fb7e711cb403bcbbd92e30ae0482fa5ed7629d644962076351563e60a07cc93aa47fc63533a3f3015e8'
-  data.tar.gz: c81810d3ec0184a8283a3e9e5ce0d124f9bc762350a6d7bb2aa92c406825788dc3bee83384b2a4093f767aca5201835b48cd55ab7f3e813f2cb40cb228d399b8
+  metadata.gz: 21a997d93ee9f729af3ec4f14ebb287aca527d59cfa4f425c520156a19da7564f3f3c98c9680875f01afadfccf60fb1efc503a2a305f4274fab1cc75de06b11d
+  data.tar.gz: 31dbb1ca9b278348d3cc1405980db89649024b69788bc1983827dca9d8a998570389f96725be45edd83e7f92578cd7bdb2c0cdf2f20230737c2ba570d204ad2a

data/CHANGELOG.md

@@ -7,10 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-20
+
+### Added
+
+- Support hosts whose `active_storage_attachments.record_id` is a UUID. The migrations read that column and give `open_blog_images` and `open_blog_authors` UUID primary keys, with UUID `author_id`, `cover_image_id`, and `social_image_id` post references, when it is a UUID. Integer-keyed hosts keep integer keys. No host table changes and no setting.
+- Add the `AlignOpenBlogRecordKeys` migration. It converts the image and author keys of a 0.2.0 installation on a UUID attachment table and keeps every row and reference; on an integer-keyed host it does nothing.
+- Add the doctor **Record keys** check. It reports blog keys that cannot be attachment records, and, with rich-text bodies enabled, Action Text keys that do not match the post or attachment keys.
+- Serve card thumbnails and author avatars from the engine route `/blog/media/:sha256/:variant/:filename` (`card` or `avatar`), delivered through `config.image_delivery` like the originals.
+
+### Changed
+
+- Card and avatar images no longer use the host's Active Storage representation routes, so a host can keep `ActiveStorage::Representations::RedirectController` and `ProxyController` closed.
+- On a UUID-keyed host, `image_id` and author `id` values in the JSON API and MCP tool schemas are UUID strings.
+
+### Upgrade notes
+
+- Run `bin/rails railties:install:migrations FROM=open_blog` and `bin/rails db:migrate`; doctor reports an error until `AlignOpenBlogRecordKeys` has run. On an integer-keyed host the migration makes no schema change.
+- Copied reader templates need no change: `open_blog_card_image` and `open_blog_avatar` emit the new URLs. A host template that builds its own variant URL with `main_app.url_for` still needs the host's representation routes.
+- JSON stays below version 3: Rails 8.0 does not work with JSON 3.
+
 ## [0.2.0] - 2026-10-10
 
 ### Added
 
+- Add a Usage guide and an existing-host integration recipe covering shared layouts, application colors, theme controls, image compatibility, and copied-file upgrades; expand the packaged install skill and document agent skill loading.
 - Add three reader presets, Signal, Editorial, and Ink, selected with `config.theme`. Each has light and dark values that meet WCAG 2.2 AA contrast.
 - Ship the preset fonts (Outfit, DM Sans, Newsreader, Space Grotesk, and JetBrains Mono) as woff2 files with their license texts. No font loads from another site.
 - Add `config.theme_colors` for hex color overrides of the preset, for both modes or per mode. Doctor warns when an override takes a text and background pair below 4.5:1; a translucent color is measured over the color under it.

data/README.md

@@ -67,6 +67,12 @@ Start `bin/dev` (or `bin/rails server`) and open `/blog`. The generator installs
 
 Set your site name, publisher, and public origin in the initializer, then run `bin/rails open_blog:doctor` to check the setup. The [installation guide](https://techwright-lab.github.io/open-blog/installation/) lists every generator option, and the [configuration reference](https://techwright-lab.github.io/open-blog/configuration/) lists every setting with its default.
 
+## Usage
+
+The [usage guide](https://techwright-lab.github.io/open-blog/usage/) explains the publishing interfaces, article lifecycle, and where to change each part of the blog. For an existing application, follow [host integration](https://techwright-lab.github.io/open-blog/host-integration/) to reuse its navbar/footer, map Signal to its colors, share its theme control, and verify images and upgrades. These visual customizations use host files and existing gem settings.
+
+For an agent, locate the packaged `skills/open-blog-install/SKILL.md` with `bundle show open_blog`. The [agent workflow guide](https://techwright-lab.github.io/open-blog/mcp/#packaged-agent-workflows) explains how to load all six skills; connecting MCP alone does not install them.
+
 ## Publish a post
 
 **From Ruby:**
@@ -97,6 +103,7 @@ A later edit of a public post must carry `change: "substantive"`, `"correction"`
 
 | Guide | Covers |
 | --- | --- |
+| [Usage](https://techwright-lab.github.io/open-blog/usage/) and [Host integration](https://techwright-lab.github.io/open-blog/host-integration/) | End-to-end workflow, file map, shared layout/colors/theme control, compatibility, and upgrades |
 | [Configuration](https://techwright-lab.github.io/open-blog/configuration/) | Identity, routes, content gates, images, limits, and page views |
 | [Publishing](https://techwright-lab.github.io/open-blog/publishing/) | Operations, previews, scheduling, approvals, and findings |
 | [JSON API](https://techwright-lab.github.io/open-blog/api/) and [MCP](https://techwright-lab.github.io/open-blog/mcp/) | Endpoints, tools, examples, and error codes |

data/app/controllers/open_blog/api/v1/authors_controller.rb

@@ -50,7 +50,7 @@ module OpenBlog
           raise Error::UnknownField.new(details: unknown.map { |field| "avatar.#{field}" }) if unknown.any?
           invalid!(:avatar) unless input.size == 1
           if input.key?(:image_id)
-            invalid!(:avatar) unless input[:image_id].is_a?(Integer)
+            invalid!(:avatar) unless RecordKeys.id?(Image, input[:image_id])
             [ nil, Image.find(input[:image_id]) ]
           else
             [ ImageImport.prepare(input), nil ]

data/app/controllers/open_blog/media_controller.rb

@@ -4,16 +4,33 @@ module OpenBlog
     rescue_from ActiveStorage::FileNotFoundError, with: :render_not_found
 
     def show
+      image = attached_image
+      deliver(image.file, content_type: image.content_type, filename: image.filename)
+    end
+
+    def variant
+      image = attached_image
+      representation = image.file.variant(Image::VARIANTS.fetch(params[:variant])).processed
+      deliver(representation, content_type: representation.content_type, filename: image.filename)
+    end
+
+    private
+
+    def attached_image
       image = Image.find_by!(sha256: params[:sha256])
       raise NotFound unless image.file.attached?
+      image
+    end
+
+    def deliver(file, content_type:, filename:)
       if OpenBlog.config.image_delivery == :proxy
-        bytes = image.file.download
+        bytes = file.download
         expires_in 365.days, public: true, immutable: true
-        send_data bytes, type: image.content_type, filename: image.filename, disposition: "inline"
+        send_data bytes, type: content_type, filename: filename, disposition: "inline"
       else
         lifetime = [ ActiveStorage.service_urls_expire_in.to_i, 365.days.to_i ].min
         expires_in lifetime, public: true
-        redirect_to image.file.blob.url(expires_in: lifetime, disposition: "inline"), allow_other_host: true
+        redirect_to file.url(expires_in: lifetime, disposition: "inline"), allow_other_host: true
       end
     end
   end

data/app/helpers/open_blog/content_helper.rb

@@ -27,19 +27,26 @@ module OpenBlog
     def open_blog_card_image(post)
       image = post.cover_image
       return tag.div(class: "ob-card-placeholder", aria: { hidden: true }) unless image
-      source = image.file.attached? ? main_app.url_for(image.file.variant(resize_to_fill: [ 640, 360 ])) : image.path
+      source = image.file.attached? ? image.variant_path(:card) : image.path
       tag.img(src: source, alt: post.cover_alt.to_s, width: 640, height: 360, loading: "lazy", class: "ob-card-image")
     end
 
     def open_blog_avatar(author, name: nil)
       name ||= author.name
       if author.avatar.attached?
-        tag.img(src: main_app.url_for(author.avatar.variant(resize_to_fill: [ 80, 80 ])), alt: name, width: 40, height: 40, class: "ob-avatar", loading: "lazy")
+        tag.img(src: open_blog_avatar_source(author), alt: name, width: 40, height: 40, class: "ob-avatar", loading: "lazy")
       else
         tag.span(name.to_s.chars.first(2).join.upcase, class: "ob-avatar ob-avatar--initials", aria: { hidden: true })
       end
     end
 
+    def open_blog_avatar_source(author)
+      @open_blog_avatar_images ||= {}
+      blob = author.avatar.blob
+      image = @open_blog_avatar_images.fetch(blob.id) { @open_blog_avatar_images[blob.id] = ImageResolution.image_for_attachment(blob) }
+      image&.persisted? ? image.variant_path(:avatar) : main_app.url_for(author.avatar.variant(Image::VARIANTS.fetch("avatar")))
+    end
+
     def open_blog_body(post)
       tag.div(Renderer.render(post, cache: @open_blog_page&.kind != :preview), class: "ob-prose", data: { open_blog_body: true })
     end

data/app/models/open_blog/image.rb

@@ -1,6 +1,7 @@
 module OpenBlog
   class Image < ApplicationRecord
     include Immutable
+    VARIANTS = { "card" => { resize_to_fill: [ 640, 360 ] }, "avatar" => { resize_to_fill: [ 80, 80 ] } }.freeze
     has_one_attached :file, service: ->(_) { OpenBlog.config.storage_service || Rails.application.config.active_storage.service }
 
     validates :sha256, presence: true, uniqueness: true, format: { with: /\A[0-9a-f]{64}\z/ }
@@ -33,6 +34,11 @@ module OpenBlog
       "#{OpenBlog.mount_path.chomp("/")}/media/#{sha256}/#{ERB::Util.url_encode(filename)}"
     end
 
+    def variant_path(name)
+      raise ArgumentError, "Unknown image variant: #{name}" unless VARIANTS.key?(name.to_s)
+      "#{OpenBlog.mount_path.chomp("/")}/media/#{sha256}/#{name}/#{ERB::Util.url_encode(filename)}"
+    end
+
     def file
       super.extend(ImmutableFile)
     end

data/app/queries/open_blog/api_post_query.rb

@@ -24,7 +24,11 @@ module OpenBlog
         invalid(field) unless value.is_a?(String) && value.present?
         model = Post.reflect_on_association(association).klass
         matches = model.where(slug: value).or(model.where(name: value))
-        matches = matches.or(model.where(id: value.to_i)) if value.match?(/\A[1-9]\d*\z/)
+        if RecordKeys.uuid?(model)
+          matches = matches.or(model.where(id: value)) if value.match?(RecordKeys::UUID)
+        elsif value.match?(/\A[1-9]\d*\z/)
+          matches = matches.or(model.where(id: value.to_i))
+        end
         relation = relation.where(id: Post.joins(association).merge(matches).select(:id))
       end
       if @filters.key?(:q)

data/config/routes.rb

@@ -38,6 +38,8 @@ OpenBlog::Engine.routes.draw do
   get "/feed.json", to: "feeds#show", as: :feed_json, format: false, defaults: { format: :json }
   get "/feed.xml", to: "feeds#show", as: :feed, format: false, defaults: { format: :xml }
   get "/sitemap.xml", to: "sitemaps#show", as: :sitemap, format: false, defaults: { format: :xml }
+  get "/media/:sha256/:variant/:filename", to: "media#variant", as: :media_variant, format: false,
+    constraints: { sha256: /[0-9a-f]{64}/, variant: /card|avatar/, filename: /[^\/]+/ }
   get "/media/:sha256/:filename", to: "media#show", as: :media, format: false, constraints: { sha256: /[0-9a-f]{64}/, filename: /[^\/]+/ }
   get "/#{OpenBlog.config.route_segments.fetch(:category)}/:slug/feed.json", to: "feeds#show", as: :category_feed_json, format: false, defaults: { format: :json }
   get "/#{OpenBlog.config.route_segments.fetch(:category)}/:slug/feed.xml", to: "feeds#show", as: :category_feed, format: false, defaults: { format: :xml }

data/db/migrate/20261003012512_create_open_blog_authors.rb

@@ -1,6 +1,6 @@
 class CreateOpenBlogAuthors < ActiveRecord::Migration[8.0]
   def change
-    create_table :open_blog_authors do |t|
+    create_table :open_blog_authors, **OpenBlog::RecordKeys.table_options(connection) do |t|
       t.string :name, null: false
       t.string :slug, null: false
       t.string :author_type, null: false, default: "person"

data/db/migrate/20261003012515_create_open_blog_images.rb

@@ -1,6 +1,6 @@
 class CreateOpenBlogImages < ActiveRecord::Migration[8.0]
   def change
-    create_table :open_blog_images do |t|
+    create_table :open_blog_images, **OpenBlog::RecordKeys.table_options(connection) do |t|
       t.string :sha256, limit: 64, null: false
       t.string :filename, null: false
       t.string :content_type, null: false

data/db/migrate/20261003012516_create_open_blog_posts.rb

@@ -1,5 +1,6 @@
 class CreateOpenBlogPosts < ActiveRecord::Migration[8.0]
   def change
+    key = OpenBlog::RecordKeys.attachment_type(connection)
     create_table :open_blog_posts do |t|
       t.string :slug, null: false
       t.string :title, null: false
@@ -8,7 +9,7 @@ class CreateOpenBlogPosts < ActiveRecord::Migration[8.0]
       t.text :search_description, null: false, default: ""
       t.string :body_format, null: false
       t.text :body_markdown
-      t.references :author, null: false, foreign_key: { to_table: :open_blog_authors }
+      t.references :author, null: false, type: key, foreign_key: { to_table: :open_blog_authors }
       t.string :author_name, null: false
       t.references :category, foreign_key: { to_table: :open_blog_categories }
       t.references :series, foreign_key: { to_table: :open_blog_series }
@@ -22,9 +23,9 @@ class CreateOpenBlogPosts < ActiveRecord::Migration[8.0]
       t.boolean :featured, null: false, default: false
       t.string :canonical_url, limit: 2048
       t.string :external_id
-      t.references :cover_image, foreign_key: { to_table: :open_blog_images }
+      t.references :cover_image, type: key, foreign_key: { to_table: :open_blog_images }
       t.string :cover_alt, null: false, default: ""
-      t.references :social_image, foreign_key: { to_table: :open_blog_images }
+      t.references :social_image, type: key, foreign_key: { to_table: :open_blog_images }
       t.string :current_revision_identifier, limit: 64
       t.references :public_revision
       t.integer :word_count, null: false, default: 0

data/db/migrate/20261020120000_align_open_blog_record_keys.rb

@@ -0,0 +1,41 @@
+class AlignOpenBlogRecordKeys < ActiveRecord::Migration[8.0]
+  REFERENCES = {
+    open_blog_authors: { author_id: false },
+    open_blog_images: { cover_image_id: true, social_image_id: true }
+  }.freeze
+
+  def up
+    return unless OpenBlog::RecordKeys.attachment_type(connection) == :uuid
+    REFERENCES.each { |table, columns| convert(table, columns) unless key_type(table) == :uuid }
+  end
+
+  # Keys converted to UUID match the attachment table, as the create migrations now make them.
+  def down
+  end
+
+  private
+
+  def key_type(table)
+    connection.columns(table).find { |column| column.name == "id" }.type
+  end
+
+  def convert(table, columns)
+    add_column table, :uuid_id, :uuid, null: false, default: -> { "gen_random_uuid()" }
+    columns.each do |column, nullable|
+      remove_foreign_key :open_blog_posts, column: column
+      add_column :open_blog_posts, "#{column}_uuid", :uuid
+      execute <<~SQL.squish
+        UPDATE open_blog_posts SET #{column}_uuid = #{table}.uuid_id
+        FROM #{table} WHERE #{table}.id = open_blog_posts.#{column}
+      SQL
+      remove_column :open_blog_posts, column
+      rename_column :open_blog_posts, "#{column}_uuid", column
+      change_column_null :open_blog_posts, column, false unless nullable
+      add_index :open_blog_posts, column
+    end
+    remove_column table, :id
+    rename_column table, :uuid_id, :id
+    execute "ALTER TABLE #{table} ADD PRIMARY KEY (id)"
+    columns.each_key { |column| add_foreign_key :open_blog_posts, table, column: column }
+  end
+end

data/lib/open_blog/api_fields.rb

@@ -29,7 +29,7 @@ module OpenBlog
         next if value.nil?
         raise Error::ImageNotPermitted unless value.is_a?(Hash) && value.size == 1
         if value.key?(:image_id)
-          raise Error::ImageNotPermitted unless value[:image_id].is_a?(Integer) && value[:image_id].positive?
+          raise Error::ImageNotPermitted unless RecordKeys.id?(Image, value[:image_id])
         else
           key = value.keys.first
           raise Error::ImageNotPermitted unless %i[signed_id url].include?(key) && value[key].is_a?(String)

data/lib/open_blog/doctor.rb

@@ -11,7 +11,7 @@ module OpenBlog
 
     CHECKS = { "Configuration" => :configuration, "Migrations" => :migrations, "Route" => :route,
       "Views" => :views, "Theme" => :theme, "JavaScript" => :javascript, "Authentication" => :authentication,
-      "Rate limit" => :rate_limit, "Jobs" => :jobs, "Storage" => :storage, "Policy pages" => :policy_pages,
+      "Rate limit" => :rate_limit, "Jobs" => :jobs, "Storage" => :storage, "Record keys" => :record_keys, "Policy pages" => :policy_pages,
       "Records" => :records, "Declarations" => :declarations }.freeze
     TABLES = %w[open_blog_authors open_blog_categories open_blog_series open_blog_images open_blog_posts
       open_blog_api_tokens open_blog_pages open_blog_page_views open_blog_faqs open_blog_tags open_blog_taggings open_blog_redirects open_blog_revisions
@@ -126,6 +126,35 @@ module OpenBlog
       [ "ok", "Active Storage and the configured image processor are available." ]
     end
 
+    def record_keys
+      if (missing_tables & %w[active_storage_attachments open_blog_images open_blog_authors open_blog_posts action_text_rich_texts]).any?
+        return [ "warning", "Record keys cannot be checked until all content tables are installed." ]
+      end
+      attachment = key_kind("active_storage_attachments", "record_id")
+      owners = %w[open_blog_images open_blog_authors].reject { |table| key_kind(table, "id") == attachment }
+      if owners.any?
+        return [ "error", "active_storage_attachments.record_id is #{attachment}, but #{owners.map { |table| "#{table}.id is #{key_kind(table, 'id')}" }.join(' and ')}, " \
+          "so blog images and avatars cannot attach. Install and run the latest migrations: " \
+          "bin/rails railties:install:migrations FROM=open_blog, then bin/rails db:migrate." ]
+      end
+      if @config.body_formats.include?(:rich_text)
+        problems = []
+        if key_kind("action_text_rich_texts", "record_id") != key_kind("open_blog_posts", "id")
+          problems << "action_text_rich_texts.record_id is #{key_kind('action_text_rich_texts', 'record_id')}, but open_blog_posts.id is #{key_kind('open_blog_posts', 'id')}, so rich-text bodies cannot save"
+        end
+        if key_kind("action_text_rich_texts", "id") != attachment
+          problems << "action_text_rich_texts.id is #{key_kind('action_text_rich_texts', 'id')}, but active_storage_attachments.record_id is #{attachment}, so rich-text bodies cannot embed images"
+        end
+        return [ "error", "#{problems.join('; ')}. Use config.body_formats = [ :markdown ] with these host tables." ] if problems.any?
+      end
+      [ "ok", "Blog image and author IDs match active_storage_attachments.record_id (#{attachment})." ]
+    end
+
+    def key_kind(table, column)
+      found = ActiveRecord::Base.connection.columns(table).find { |candidate| candidate.name == column }
+      { uuid: "uuid", integer: "integer" }.fetch(found.type, found.sql_type)
+    end
+
     def policy_pages
       problems = %i[responsible_party corrections editorial ai_use].filter_map do |key|
         url = @config.policy_urls[key]

data/lib/open_blog/mcp/registry.rb

@@ -22,12 +22,12 @@ module OpenBlog
           endpoint("remove_post", :publish, "posts", :destroy, fields: ApiFields::REMOVE, id: :required),
           upload_definition,
           endpoint("list_categories", :read, "categories", :index, fields: ApiFields::PAGE),
-          endpoint("save_category", :write, "categories", :create, fields: ApiFields::CATEGORY, id: :optional, upsert: true),
+          endpoint("save_category", :write, "categories", :create, fields: ApiFields::CATEGORY, id: :optional, upsert: Category),
           endpoint("list_tags", :read, "tags", :index, fields: ApiFields::PAGE),
           endpoint("list_authors", :read, "authors", :index, fields: ApiFields::PAGE),
-          endpoint("save_author", :write, "authors", :create, fields: ApiFields::AUTHOR, id: :optional, upsert: true),
+          endpoint("save_author", :write, "authors", :create, fields: ApiFields::AUTHOR, id: :optional, upsert: Author),
           endpoint("list_series", :read, "series", :index, fields: ApiFields::PAGE),
-          endpoint("save_series", :write, "series", :create, fields: ApiFields::SERIES, id: :optional, upsert: true),
+          endpoint("save_series", :write, "series", :create, fields: ApiFields::SERIES, id: :optional, upsert: Series),
           endpoint("list_redirects", :read, "redirects", :index, fields: ApiFields::PAGE),
           endpoint("save_redirect", :publish, "redirects", :create, fields: ApiFields::REDIRECT, required: [ :old_path ]),
           site_page_definition("get_site_page", :read),
@@ -43,7 +43,7 @@ module OpenBlog
 
       def endpoint(name, scope, controller, action, fields: [], id: nil, required: [], force: {}, upsert: false, create_publish: false, properties: nil)
         properties ||= Schemas.fields(fields)
-        properties = properties.merge("id" => upsert ? { type: "integer", minimum: 1 } : Schemas.identifier) if id
+        properties = properties.merge("id" => upsert ? Schemas.key(upsert) : Schemas.identifier) if id
         required = required + (id == :required ? [ :id ] : [])
         force.each { |key, value| properties[key.to_s] = properties.fetch(key.to_s).merge(const: value) if properties.key?(key.to_s) }
         definition(name, scope, Schemas.object(properties, required: required)) do |arguments, actor:, base_url:|

data/lib/open_blog/mcp/schemas.rb

@@ -15,6 +15,10 @@ module OpenBlog
         { anyOf: [ { type: "integer", minimum: 1 }, { type: "string", minLength: 1 } ] }
       end
 
+      def key(model)
+        RecordKeys.uuid?(model) ? { type: "string", format: "uuid" } : { type: "integer", minimum: 1 }
+      end
+
       def fields(names)
         names.to_h { |name| [ name.to_s, field(name) ] }
       end
@@ -44,7 +48,7 @@ module OpenBlog
           object(fields(%i[reviewer_name approved_at facts_checked evidence confirmed_by]), required: %w[reviewer_name approved_at facts_checked evidence confirmed_by])
         when :old_slugs
           { type: "array", items: { anyOf: [ text, object(fields(%i[slug moved_on]), required: [ "slug" ]) ] } }
-        when :image_id then { type: "integer", minimum: 1 }
+        when :image_id then key(Image)
         when :type then { type: "string", enum: %w[person organization] }
         when :body_format then { type: "string", enum: %w[markdown rich_text] }
         when :provenance then { type: "string", enum: %w[ai_assisted human_written unknown] }

data/lib/open_blog/post_attributes.rb

@@ -106,7 +106,7 @@ module OpenBlog
       when Integer then Author.find(input)
       when String
         invalid(:author) if input.blank?
-        if input.match?(/\A[1-9]\d*\z/)
+        if input.match?(/\A[1-9]\d*\z/) || RecordKeys.uuid_id?(Author, input)
           Author.find(input)
         else
           Author.find_by(slug: input) || Author.find_by(name: input) || Author.create!(name: input)
@@ -154,7 +154,7 @@ module OpenBlog
       return Image.find(input) if input.is_a?(Integer)
       if input.is_a?(Hash) && input.keys.map(&:to_s) == [ "image_id" ]
         id = input[:image_id] || input["image_id"]
-        return Image.find(id) if id.is_a?(Integer) || (id.is_a?(String) && id.match?(/\A[1-9]\d*\z/))
+        return Image.find(id) if id.is_a?(Integer) || (id.is_a?(String) && id.match?(/\A[1-9]\d*\z/)) || RecordKeys.uuid_id?(Image, id)
       end
       raise Error::ImageNotPermitted
     end

data/lib/open_blog/record_keys.rb

@@ -0,0 +1,35 @@
+module OpenBlog
+  # Copied host migrations call these methods, so their names and arguments must stay stable.
+  module RecordKeys
+    UUID = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+    ATTACHING_TABLES = %w[open_blog_images open_blog_authors].freeze
+
+    module_function
+
+    def attachment_type(connection)
+      if connection.data_source_exists?("active_storage_attachments")
+        column = connection.columns("active_storage_attachments").find { |candidate| candidate.name == "record_id" }
+        column&.type == :uuid ? :uuid : :bigint
+      else
+        generators = Rails.configuration.generators
+        generators.options.dig(generators.orm, :primary_key_type)&.to_sym == :uuid ? :uuid : :bigint
+      end
+    end
+
+    def table_options(connection)
+      attachment_type(connection) == :uuid ? { id: :uuid } : {}
+    end
+
+    def uuid?(model)
+      model.type_for_attribute(model.primary_key).type == :uuid
+    end
+
+    def id?(model, value)
+      uuid?(model) ? value.is_a?(String) && value.match?(UUID) : value.is_a?(Integer) && value.positive?
+    end
+
+    def uuid_id?(model, value)
+      uuid?(model) && value.is_a?(String) && value.match?(UUID)
+    end
+  end
+end

data/lib/open_blog/version.rb

@@ -1,3 +1,3 @@
 module OpenBlog
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/open_blog.rb

@@ -58,6 +58,7 @@ module OpenBlog
   autoload :Mcp, "open_blog/mcp"
   autoload :ApiFields, "open_blog/api_fields"
   autoload :Authentication, "open_blog/authentication"
+  autoload :RecordKeys, "open_blog/record_keys"
 
   class << self
     def config

data/skills/open-blog-install/SKILL.md

@@ -1,10 +1,58 @@
 ---
 name: open-blog-install
-description: Install and configure Open Blog in a Rails host, customize its reader theme, and check setup.
+description: Install or upgrade Open Blog in a Rails host, reuse application navigation and colors, integrate the theme control, and diagnose setup compatibility.
 ---
 
-Install the gem in the requested Rails application, then run `bin/rails generate open_blog:install`. Inspect the host's JavaScript, Tailwind, image processor, mount path, and authentication setup before selecting options. Use `--skip-tailwind` when the host should keep its CSS configuration; select a reader preset with `--theme=signal`, `--theme=editorial`, or `--theme=ink`. For branding, set hex colors in `config.theme_colors`, and use the generated theme override for fonts and shape.
+## Locate the host and package
 
-Run `bin/rails open_blog:doctor` or `blog_doctor` and resolve relevant errors. Configure the actual publisher, author, public base URL, and policy links. Replace placeholders with user-supplied identities. Keep the initial API token secret; installation prints it once and repeat runs do not recover it. A host authentication hook takes precedence over tokens.
+Work from the requested application's Rails root. Inspect its public layout and shared navbar/footer, CSS pipeline and palette variables, JavaScript entrypoint and Stimulus registration, existing theme preference, mount path, and editorial authentication. For a pilot, select isolated development/test databases before migrating.
 
-Check `tools/list` before using MCP tools. Finish with an actual reader request and authenticated `blog_list_posts` call. Do not publish unrelated content, change production routing, or deploy merely because installation was requested.
+Use the requested gem release; inspect `Gemfile.lock` and `bundle show open_blog`. The installed package is the authority for its version. Inside it, layout and reader templates are under `lib/generators/open_blog/install/templates/views/`, theme sources under `lib/generators/open_blog/install/templates/theme/`, and browser controllers under `app/assets/javascripts/open_blog/controllers/`.
+
+For examples and explanations, read [host integration](https://techwright-lab.github.io/open-blog/host-integration/); for task/file routing, read [usage](https://techwright-lab.github.io/open-blog/usage/). In a source checkout these are `docs/host-integration.md` and `docs/usage.md`. The steps below remain usable from the installed gem without the documentation site.
+
+## Check images before calling setup complete
+
+- Inspect `active_storage_attachments.record_id` in the schema or with `ActiveStorage::Attachment.columns_hash.fetch("record_id").sql_type`. From 0.3.0 the migrations give Image and Author UUID keys when this column is `uuid`, and integer keys otherwise; doctor's Record keys check must report ok. A host that installed 0.2.0 on a UUID column needs `bin/rails railties:install:migrations FROM=open_blog` and `db:migrate` (the `AlignOpenBlogRecordKeys` migration). Keep the existing host attachment schema intact. With rich-text bodies, also follow doctor's Action Text key result; use Markdown when it reports a mismatch.
+- Inspect the host variant processor before running the installer. It accepts `:vips` or `:mini_magick`; a disabled processor requires host configuration. Verify Ruby image-processing dependencies and native libvips/ImageMagick in the deployment image and production gem groups.
+- Card and avatar variants use the engine's `/blog/media/:sha256/:variant/:filename` route and `config.image_delivery`, not the host's representation routes, so a host can keep those closed. Test originals and both variant URLs independently. Use `:proxy` when the host also blocks the storage service URLs that `:redirect` sends readers to. Preserve existing host access restrictions.
+
+## Install and configure
+
+Add a missing gem with `bundle add open_blog`, passing the requested version constraint when specified. For a fresh application, use `bin/rails generate open_blog:install`. For an existing application retaining its CSS pipeline, use `--skip-tailwind`. A staged local pilot can use:
+
+```sh
+bin/rails generate open_blog:install --theme=signal --skip-tailwind --skip-migrate --skip-sample
+```
+
+Choose the requested preset. These flags still write files, add dependencies, register JavaScript, and mount routes. Review migrations and the host diff, migrate the intended database, then run `bin/rails open_blog:doctor`. Create the initial token with `open_blog:install_token` only when the selected access method needs it; keep the one-time secret private. A configured authentication hook takes precedence over tokens. Run `open_blog:sample` only when sample publishing is wanted and image setup works.
+
+Set actual publisher/author identities, public origin (including the local port for a pilot), mount path, and policy links in `config/initializers/open_blog.rb`. The public origin excludes the mount prefix. Keep `config.mount_path` and `config/routes.rb` consistent. Restart after initializer changes.
+
+## Reuse application chrome
+
+When shared navigation is requested, extract any inline public header/footer to host partials and render them in both the homepage and blog. Prefer a host-owned `app/views/layouts/blog.html.erb` with `config.layout = "blog"` when the main layout needs different behavior; `open_blog:views` does not overwrite that filename. Direct `config.layout = "application"` is also supported: branch on `@open_blog_page` for blog-specific head/assets. Layout selection is separate from `parent_controller`, whose inherited callbacks may require authentication or unavailable host state.
+
+Adapt the installed layout while preserving `open_blog_theme_attributes`, `open_blog_head(@open_blog_page)`, early theme restoration, `open_blog_structured_data(@open_blog_page)`, `main#open-blog-main`, and the reader yield. Replace equivalent host head tags on reader requests so title/viewport/canonical are not duplicated. Keep host CSRF/CSP, icons, and required assets. Retain the reader's content/notices/byline/date helpers and policy/feed links, using a shared footer slot if needed. Host links in engine-rendered shared partials use `main_app`, for example `main_app.root_path`.
+
+For `--skip-tailwind`/Tailwind 3, load the host's CSS explicitly and then `open_blog_stylesheets` (preset, compiled reader CSS, host override). For the Tailwind 4 component build, use `open_blog_theme_stylesheets` before the host build instead, keeping its generated `open_blog/theme.css` import. Register the `open-blog--` controllers in the public JavaScript entrypoint. Avoid `stylesheet_link_tag :all`; the compiled reader stylesheet contains reset rules. Scope `.ob-page` to the reader and inspect shared chrome after loading it.
+
+## Share palette and appearance state
+
+Use `config.theme_colors` for fixed hex colors. For host CSS variables, edit `app/assets/stylesheets/open_blog_theme.css` (fallback CSS) or `app/assets/tailwind/open_blog/theme.css` (Tailwind 4). Map semantic `--ob-*` colors to host tokens; `var()` is invalid in `theme_colors`. Override both explicit and system-mode specificity, for example the selector list `:root[data-ob-theme="signal"][data-theme], :root[data-ob-theme="signal"]:not([data-theme])`, loaded after preset rules. Cover surfaces, text, borders, accents, code, notices, and alerts. Keep Signal typography/shape if requested. Use opaque surface mixes where translucent host colors expose unwanted layers. Doctor does not check CSS-derived contrast.
+
+Place a single theme button in the shared navbar if requested; it is not a separate nav. Reuse the existing `open-blog--theme` controller and `cycle` action, its `systemLabel`/`lightLabel`/`darkLabel` values, and optional `label` target. Keep the initial `hidden` attribute, accessible mode label, keyboard focus, and mobile target size. The installed `_theme_toggle.html.erb` shows its markup; a host partial can use host styles.
+
+The controller stores `open-blog-theme` and sets `data-theme="light"` or `"dark"` on `<html>`; System removes both and follows the OS. Restore that same key before CSS loads on homepage and blog using the gem helper or one shared equivalent script with the host's CSP nonce. Keep one preference owner when the host already has a theme controller. Honor a fixed `config.color_scheme` by retaining its root attribute and omitting the toggle. Check Turbo transitions if used, full reloads, explicit light/dark, and system mode.
+
+## Upgrade copied files deliberately
+
+Read the target changelog, update any version constraint, then `bundle update open_blog --conservative`; review dependency changes too (Open Blog constrains JSON below 3). Bundler does not refresh copied host files.
+
+`bin/rails generate open_blog:views` refreshes reader templates and `layouts/open_blog.html.erb` only. Compare controllers, locales, and theme sources with the installed package separately. Conflicting files are kept in a noninteractive rerun; a successful generator exit does not mean all copies are current. Merge required changes and use replacement only for reviewed files. A blanket `open_blog:install --force` also replaces the initializer. Review a host-owned layout against new helper/asset contracts manually. When moving from 0.1.0 to presets, replace old full-palette definitions with intentional overrides so they do not mask the new preset. Rebuild affected assets and restart.
+
+## Verify and report
+
+Run doctor, relevant host regression tests, and real reader requests. Verify shared links/chrome, a single head/landmark, fonts and computed palette in all modes, preference persistence, keyboard access, and desktop/mobile overflow. Exercise a real upload and variant retrieval separately from text-only rendering; preserve host attachment regressions. Verify feeds/sitemap and any promised scheduling with the actual worker, not only a direct job invocation.
+
+For MCP use, check `tools/list` and make an authenticated `blog_list_posts` call when that access is configured. Exercise draft privacy and signed previews; perform publication/edit checks within authorized local/test scope. Report observed passes, blockers, and unverified checks separately. Installation does not authorize unrelated content publication or production deployment.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: open_blog
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - TechWright Labs
 bindir: bin
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -365,6 +365,7 @@ files:
 - db/migrate/20261003164418_create_open_blog_api_tokens.rb
 - db/migrate/20261003175454_create_open_blog_pages.rb
 - db/migrate/20261003182919_create_open_blog_page_views.rb
+- db/migrate/20261020120000_align_open_blog_record_keys.rb
 - lib/generators/open_blog/admin_suite/admin_suite_generator.rb
 - lib/generators/open_blog/admin_suite/templates/author_resource.rb.tt
 - lib/generators/open_blog/admin_suite/templates/blog_portal.rb.tt
@@ -469,6 +470,7 @@ files:
 - lib/open_blog/reader_dates.rb
 - lib/open_blog/reader_page.rb
 - lib/open_blog/reader_queries.rb
+- lib/open_blog/record_keys.rb
 - lib/open_blog/record_release.rb
 - lib/open_blog/redirect_target.rb
 - lib/open_blog/remove.rb