shiplog 0.2.0 → 0.3.1

data/config/locales/es.yml

@@ -0,0 +1,223 @@
+# Textos de Shiplog en español. Los hosts pueden sobrescribir cualquier clave en sus propios archivos de idioma.
+es:
+  activerecord:
+    attributes:
+      shiplog/entry:
+        changelog_kind: Categoría
+  # Los nombres de los meses que usa el formato de fecha de Shiplog (rails-i18n los trae también; son los mismos).
+  date:
+    month_names: [~, enero, febrero, marzo, abril, mayo, junio, julio, agosto, septiembre, octubre, noviembre, diciembre]
+  shiplog:
+    columns:
+      in_progress: En desarrollo
+      coming_soon: Próximamente
+      later: Más adelante
+      in_progress_description: Lo que estamos construyendo ahora
+      coming_soon_description: Lo siguiente en la lista
+      later_description: En nuestro radar
+    categories:
+      feature: Nuevo
+      change: Mejorado
+    empty: Todavía no hay nada
+    date_format: "%-d de %B de %Y"
+    roadmap:
+      title: Hoja de ruta
+      lede: En qué estamos trabajando y qué viene después.
+      parts:
+        one: Incluye %{count} parte
+        other: Incluye %{count} partes
+      shipped_heading: Lanzado recientemente
+      shipped_date_format: "%-d de %B"
+      full_changelog: Ver el registro de cambios completo
+      footnote: ""
+      suggest: Sugerir una función
+    switcher:
+      label: Actualizaciones del producto
+      roadmap: Hoja de ruta
+      changelog: Registro de cambios
+    changelog:
+      title: Registro de cambios
+      lede: Nuevas funciones y mejoras, a medida que se lanzan.
+      pagination:
+        label: Paginación
+        older: Anteriores
+        newer: Más recientes
+      search:
+        label: Buscar en el registro de cambios
+        submit: Buscar
+        summary:
+          one: "%{count} resultado para “%{query}”"
+          other: "%{count} resultados para “%{query}”"
+        clear: Borrar búsqueda
+        empty: "Ninguna entrada coincide con “%{query}”."
+      areas:
+        label: Filtrar por área
+        all: Todas
+    permalink:
+      title: "%{title} · %{changelog}"
+      back: "← Volver al registro de cambios"
+      nav_label: Más cambios
+      newer: "← Más reciente: %{title}"
+      older: "Anterior: %{title} →"
+    feed:
+      title_with_product: "Registro de cambios de %{product}"
+      link_title: Registro de cambios (Atom)
+      subscribe: Suscribirse (Atom)
+    admin:
+      title: Administración de Shiplog
+      nav:
+        drafts: Borradores
+        board: Tablero de la hoja de ruta
+        sync: Sincronización
+        areas: Áreas
+      areas:
+        title: Áreas del producto
+        help: La IA agrupa las entradas en áreas (como máximo %{max}) mientras las reescribe. Los visitantes pueden filtrar el registro de cambios por área cuando hay dos áreas con entradas publicadas.
+        detect: Detectar áreas
+        recheck: Revisar de nuevo las entradas sin área
+        recheck_help: Vuelve a preguntar a la IA por las entradas que dejó sin área, por ejemplo después de renombrar, fusionar o añadir áreas.
+        no_rewriter: La detección necesita config.rewriter, que no está configurado.
+        last_detection: "Última detección: %{time}, %{count} asignadas"
+        last_error: "La última detección falló (%{time}): %{error}"
+        detection_queued: Detección en cola. Actualiza en un momento.
+        translate_names: Traducir nombres
+        translate_names_help: Pide a la IA los nombres que faltan en algún idioma. Los nombres que ya existen, incluidos los que editaste, se conservan.
+        no_locales: Traducir los nombres necesita config.locales, que está vacío.
+        no_rewriter_translate: Traducir los nombres necesita config.rewriter, que no está configurado.
+        translation_queued:
+          one: Traducción en cola para %{count} área. Actualiza en un momento.
+          other: Traducción en cola para %{count} áreas. Actualiza en un momento.
+        empty: Todavía no hay áreas. Detecta áreas para que se propongan a partir de tus entradas.
+        columns:
+          name: Nombre
+          entries: Entradas
+          order: Orden
+          merge: Fusionar con
+        name_label: Nombre
+        rename: Renombrar
+        renamed: Área renombrada.
+        move_up: Subir
+        move_down: Bajar
+        merge: Fusionar
+        merge_into: Fusionar con
+        merged: "%{from} se fusionó con %{into}."
+        merge_target: Elige otra área con la que fusionar.
+        merge_help: Al fusionar, las entradas pasan a la otra área y esta se elimina. Si eliminas un área, sus entradas se quedan sin área.
+        delete: Eliminar
+        deleted: Área eliminada. Sus entradas ya no tienen área.
+      entries:
+        title: Entradas
+        filters: Filtrar entradas
+        all_kinds: Todos los tipos
+        empty: Ninguna entrada coincide.
+        pagination: Paginación
+        older: Anteriores
+        newer: Más recientes
+        saved: Entrada guardada.
+        approved: Entrada aprobada.
+        discarded: Entrada descartada.
+        restored: Entrada devuelta a borrador.
+        invalid_transition: Esa acción no está disponible para esta entrada en su estado actual.
+        rewrite_queued: Reescritura en cola. Actualiza en un momento.
+        edit: Editar
+        edit_title: "Editar %{kind}"
+        approve: Aprobar
+        discard: Descartar
+        restore: Restaurar
+        save: Guardar
+        regenerate: Regenerar
+        no_area: Ninguna
+        area_gone: ya no existe
+        regenerate_warning: Al regenerar, esta entrada deja de estar publicada hasta que se apruebe de nuevo.
+        source_changed: El texto de GitHub cambió desde este borrador
+        rewrite_error: Falló la reescritura
+        not_rewritten: Todavía sin reescribir
+        public_text: Texto público
+        source: Origen en GitHub
+        back: Volver a los borradores
+        images:
+          title: Capturas de pantalla
+          help: Se muestran bajo el texto en el registro de cambios (la primera en la lista, todas en la página de la entrada). Se toman de la incidencia o del pull request de GitHub al escribir el borrador; también puedes subir las tuyas.
+          empty: Todavía no hay capturas.
+          alt: Texto alternativo
+          alt_placeholder: Describe la imagen (por defecto, el título)
+          save_alt: Guardar texto alternativo
+          remove: Quitar
+          move_up: Subir
+          move_down: Bajar
+          upload: Subir imágenes
+          upload_label: Imágenes (PNG, JPEG, GIF o WebP, hasta 5 MB cada una)
+          none_selected: Elige al menos una imagen.
+          rejected: "No se añadieron; solo se aceptan imágenes PNG, JPEG, GIF y WebP de hasta 5 MB y 10.000 píxeles por lado: %{names}"
+          added:
+            one: Imagen añadida.
+            other: "%{count} imágenes añadidas."
+          alt_saved: Texto alternativo guardado.
+          removed: Imagen quitada.
+          moved: Imagen movida.
+        translations:
+          title: Traducciones
+          help: "Al aprobar una entrada, esta se traduce automáticamente, y la traducción se publica junto con el texto en inglés. Una traducción que edites se conserva hasta que cambie el texto en inglés; entonces se vuelve a traducir. Una traducción desactualizada o ausente no se muestra: los visitantes ven el texto en inglés."
+          not_approved: Las traducciones se escriben cuando se aprueba la entrada.
+          missing: Falta
+          stale: Desactualizada
+          current: Al día
+          edited: Editada por un administrador
+          retranslate: Traducir de nuevo
+          saved: Traducción guardada.
+          queued: Traducción en cola. Actualiza en un momento.
+          only_approved: Solo se traducen las entradas aprobadas.
+          no_rewriter: Para traducir hace falta config.rewriter, que no está configurado.
+        category_options:
+          feature: Nueva función
+          change: Mejora
+        statuses:
+          draft: Borradores
+          approved: Aprobadas
+          discarded: Descartadas
+        kinds:
+          roadmap: Hoja de ruta
+          feature: Función
+          change: Cambio
+        columns:
+          entry: Entrada
+          kind: Tipo
+          source: Origen
+          actions: Acciones
+        fields:
+          title: Título
+          body: Texto
+          released_on: Fecha de lanzamiento
+          category: Categoría
+          area: Área
+          reason: Motivo
+      board:
+        title: Tablero de la hoja de ruta
+        help: Arrastra las tarjetas entre columnas para fijarlas y ordenarlas. Sin JavaScript, usa el botón Mover de cada tarjeta.
+        updated: Tablero actualizado.
+        not_approved: Sin aprobar
+        pinned: Fijada
+        move_to: Mover a
+        move: Mover
+        unpin: Quitar de fijadas
+      sync:
+        title: Estado de la sincronización
+        queued: Sincronización en cola.
+        webhook_secret_missing: El secreto del webhook no está configurado, así que se rechazan los webhooks de GitHub.
+        github_token_missing: El token de GitHub no está configurado, así que no se puede sincronizar.
+        sync_now: Sincronizar ahora
+        sync_and_scan: Sincronizar y buscar cambios
+        repositories: Repositorios
+        no_repositories: No hay repositorios configurados.
+        repository: Repositorio
+        synced_at: Última sincronización
+        changes_scanned_at: Cambios revisados
+        last_error: Último error
+        never: Nunca
+        deliveries: Últimas entregas de webhook
+        no_deliveries: Todavía no hay entregas.
+        event: Evento
+        action: Acción
+        received_at: Recibida
+        processed_at: Procesada
+        error: Error

data/config/routes.rb

@@ -1,5 +1,10 @@
 Shiplog::Engine.routes.draw do
   get Shiplog.config.roadmap_path, to: "roadmaps#show", as: :roadmap
+  # The feed and the permalinks come before the plain changelog route, whose optional (.:format) would
+  # otherwise take /changelog.atom. A slug has no dot, and the permalink takes no format.
+  get "#{Shiplog.config.changelog_path}.atom", to: "changelog_feeds#show", as: :changelog_feed, defaults: { format: "atom" }
+  get "#{Shiplog.config.changelog_path}/:slug", to: "changelog_entries#show", as: :changelog_entry,
+    format: false, constraints: { slug: /[a-z0-9-]+/ }
   get Shiplog.config.changelog_path, to: "changelogs#show", as: :changelog
   post "shiplog/github/webhook", to: "webhooks#create", as: :github_webhook
   get "shiplog/assets/:version/:name", to: "frontends#show", as: :frontend, constraints: { version: /[^\/]+/, name: /[a-z_]+\.(css|js)/ }

data/db/migrate/20261027000002_shiplog_0_3_0.rb

@@ -0,0 +1,105 @@
+# Everything 0.3.0 adds to the schema, one section per feature. Additive and reversible.
+class Shiplog030 < ActiveRecord::Migration[8.1]
+  # A migration must not depend on model code that changes later: this is a bare table-backed class.
+  class MigrationEntry < ActiveRecord::Base
+    self.table_name = "shiplog_entries"
+    self.inheritance_column = nil
+  end
+
+  SLUG_MAX_LENGTH = 80
+
+  def change
+    # --- Entry permalinks (/changelog/:slug) ---
+    # Set when an entry is first approved, never changed afterwards, so links never break. Nil for roadmap
+    # entries and drafts. Entries approved before 0.3.0 get theirs here (oldest first, so the oldest keeps the
+    # plain slug on duplicate titles): the public pages never write, so nothing else fills them in.
+    add_column :shiplog_entries, :slug, :string
+    add_index :shiplog_entries, :slug, unique: true, where: "slug IS NOT NULL"
+    reversible do |direction|
+      direction.up do
+        MigrationEntry.reset_column_information
+        backfill_slugs
+      end
+    end
+
+    # --- "What's new" unseen count ---
+    # `Shiplog.unseen_count` counts approved feature and change entries with `approved_at > since`:
+    # an equality column first, then the range column.
+    add_index :shiplog_entries, [ :status, :approved_at ]
+
+    # --- Product areas (detected by AI) ---
+    # `entries.area_id` is nullable; deleting an area nullifies it (merging moves the entries first).
+    # `area_set_by_admin` marks an area chosen by hand, which detection never overwrites.
+    create_table :shiplog_areas do |t|
+      t.string :name, null: false
+      t.string :slug, null: false
+      t.integer :position, null: false, default: 0
+      # The name in each of config.locales, keyed by locale string ({ "es" => "Listas de embalaje" }); empty
+      # until translated. Slugs stay English, so ?area= URLs are shared across locales.
+      t.jsonb :name_translations, null: false, default: {}
+      t.timestamps
+    end
+    add_index :shiplog_areas, :slug, unique: true
+    add_reference :shiplog_entries, :area, null: true, index: true, foreign_key: { to_table: :shiplog_areas, on_delete: :nullify }
+    add_column :shiplog_entries, :area_set_by_admin, :boolean, null: false, default: false
+    # When detection last asked the AI about the entry (placed or not): unplaced entries are not asked again
+    # until an admin asks for a re-check.
+    add_column :shiplog_entries, :area_detected_at, :datetime
+    # A small key-value store for state that belongs to no record, e.g. the result of the last area detection
+    # (shown on the admin's Areas page).
+    create_table :shiplog_settings do |t|
+      t.string :key, null: false
+      t.jsonb :value, null: false, default: {}
+      t.timestamps
+    end
+    add_index :shiplog_settings, :key, unique: true
+
+    # --- Screenshots (needs Active Storage in the host; the columns are harmless without it) ---
+    # `image_order` is the ordered list of the entry's image blob ids, `image_alts` the alt text per blob id
+    # ({ "12" => "The dark theme" }); a missing alt text falls back to the entry's title.
+    add_column :shiplog_entries, :image_order, :jsonb, null: false, default: []
+    add_column :shiplog_entries, :image_alts, :jsonb, null: false, default: {}
+
+    # --- Translations of entries (config.locales) ---
+    # One row per entry and locale, published with the English text (no second approval). `source_digest` is the
+    # digest of the English title and body it was made from: a row whose digest differs from the entry's current
+    # text is stale and never shown. `edited_by_admin` keeps an admin's edit until the English text changes.
+    create_table :shiplog_entry_translations do |t|
+      t.references :entry, null: false, index: false, foreign_key: { to_table: :shiplog_entries, on_delete: :cascade }
+      t.string :locale, null: false
+      t.string :title, null: false
+      t.text :body, null: false, default: ""
+      t.string :source_digest, null: false
+      t.boolean :edited_by_admin, null: false, default: false
+      t.timestamps
+    end
+    add_index :shiplog_entry_translations, [ :entry_id, :locale ], unique: true
+  end
+
+  # Gives every approved feature and change with a release date, and no slug, one: the title as [a-z0-9-] only
+  # (cut at 80 characters), made unique with -2, -3, ...; entry-<id> when nothing is left. The same rules as
+  # Shiplog::Entry#generate_slug at the time of 0.3.0.
+  def backfill_slugs
+    taken = MigrationEntry.where.not(slug: nil).pluck(:slug).to_set
+    MigrationEntry.where(status: "approved", kind: %w[feature change], slug: nil).where.not(released_on: nil)
+      .order(:released_on, :approved_at, :id).to_a.each do |entry|
+      slug = slug_for(entry, taken)
+      taken << slug
+      MigrationEntry.where(id: entry.id, slug: nil).update_all(slug:)
+    end
+  end
+
+  private
+
+  def slug_for(entry, taken)
+    base = entry.title.to_s.parameterize.tr("_", "-").squeeze("-").first(SLUG_MAX_LENGTH).gsub(/\A-+|-+\z/, "").presence || "entry-#{entry.id}"
+    candidate = base
+    suffix = 2
+    while taken.include?(candidate)
+      tail = "-#{suffix}"
+      candidate = "#{base.first(SLUG_MAX_LENGTH - tail.length).delete_suffix("-")}#{tail}"
+      suffix += 1
+    end
+    candidate
+  end
+end

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

@@ -59,7 +59,16 @@ module Shiplog
         search_button: "rounded-md bg-indigo-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-indigo-500",
         search_summary: "mb-4 text-sm text-gray-500 dark:text-gray-400",
         search_clear: "ml-2 font-medium text-indigo-600 hover:underline dark:text-indigo-400",
-        search_empty: "text-gray-500 dark:text-gray-400"
+        search_empty: "text-gray-500 dark:text-gray-400",
+        permalink: "mx-auto max-w-2xl rounded-lg border border-gray-200 bg-white p-6 dark:border-gray-800 dark:bg-gray-900",
+        permalink_back: "mt-6 inline-block text-sm font-medium text-indigo-600 hover:underline dark:text-indigo-400",
+        permalink_nav: "mt-8 flex flex-wrap justify-between gap-4 border-t border-gray-200 pt-4 dark:border-gray-800",
+        permalink_nav_link: "text-sm font-medium text-indigo-600 hover:underline dark:text-indigo-400",
+        areas: "my-4 flex flex-wrap gap-2",
+        area_link: "rounded-full border border-gray-300 px-3 py-0.5 text-sm hover:border-indigo-500 dark:border-gray-700 [&.shiplog-areas__link--current]:border-indigo-600 [&.shiplog-areas__link--current]:bg-indigo-600 [&.shiplog-areas__link--current]:text-white",
+        entry_area: "text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400",
+        entry_images: "mt-3 grid w-full gap-3",
+        entry_image: "h-auto max-w-full rounded-lg border border-gray-200 dark:border-gray-800"
       }.freeze
 
       def copy_initializer

data/lib/generators/shiplog/install/templates/initializer.rb.tt

@@ -97,7 +97,12 @@ Shiplog.configure do |config|
 
   # Public paths, read when routes are drawn.
   # config.roadmap_path = "roadmap"
-  # config.changelog_path = "changelog"
+  # config.changelog_path = "changelog"   # a-z, 0-9, - and _; "docs/news" nests; outer slashes are stripped
+
+  # The site's canonical origin (scheme, host, optional port; no path). The Atom feed's ids and links, og:url
+  # and the other absolute URLs use it instead of the request's host, which varies (apex vs www, a forged
+  # X-Forwarded-Host). Behind a proxy, also set config.assume_ssl = true (or send X-Forwarded-Proto) in Rails.
+  # config.canonical_url = "https://example.com"
 
   # Pages added to the Roadmap / Changelog switcher. label and path are Strings, or callables evaluated in the
   # view (route helpers, I18n). Render the same switcher on your own pages with `helper Shiplog::SwitcherHelper`
@@ -117,6 +122,58 @@ Shiplog.configure do |config|
   # The public changelog's search box and ?q= filtering. Set to false to turn search off.
   # config.changelog_search = true
 
+  # schema.org structured data (JSON-LD) on the public pages: an Article on each permalink, a CollectionPage on
+  # the changelog and the roadmap. Set to false to turn it off.
+  # config.structured_data = true
+
+  # "What's new". Shiplog doesn't know your users, so you supply the "last seen" time. This is called with the
+  # controller on every changelog index or permalink view, BEFORE the page renders (a 304 revisit included), so a
+  # navbar badge in the same response is current. It may write and runs on every visit: keep it cheap, and write
+  # only when something is new. Show `Shiplog.unseen_count(since: user.changelog_seen_at)` (at most 99, counted on
+  # approved_at; `helper Shiplog::UnseenHelper` and `shiplog_unseen_count(since)` in views) next to your Changelog
+  # link. current_user is often private, hence controller.send (or read a Current attribute).
+  # config.on_changelog_seen = lambda do |controller|
+  #   user = controller.send(:current_user)
+  #   user.update_column(:changelog_seen_at, Time.current) if user && Shiplog.unseen_count(since: user.changelog_seen_at).positive?
+  # end
+
+  # The 0.3.0 migration gives entries approved so far their permalink slug. The public pages never write (a GET
+  # may hit a read replica), so an entry approved by older code during a deploy window has no permalink until
+  # `bin/rails shiplog:backfill_slugs` runs.
+
+  # With your own config.public_layout, add `<%%= shiplog_head_tags %%>` to its <head>: it renders the description,
+  # canonical link, robots, Open Graph, Twitter, Atom discovery and JSON-LD tags of the Shiplog pages (and nothing
+  # on your other pages). `except: [:feed, ...]` leaves out what your layout writes itself. The older
+  # `content_for :shiplog_og`, `:shiplog_description`, `:shiplog_feed`, `:shiplog_robots` and
+  # `:shiplog_structured_data` blocks still work but are superseded: use one or the other, never both.
+
+  # The image shared with a permalink page that has no screenshot (og:image, twitter:image, JSON-LD image): a
+  # callable evaluated in the view, so route helpers work. Return an http(s) URL or a path (made absolute); an
+  # error or any other value is logged and the page gets no image. List pages and the roadmap get none from Shiplog.
+  # config.og_image = ->(entry, locale) { main_app.url_for(controller: "/og_images", action: :show, id: entry.slug) }
+
+  # Product areas. The rewriter's reply may name an area (an existing one, or a new name of 1-3 words); Shiplog
+  # creates it while fewer than max_areas exist, so the AI cannot sprawl. The changelog offers an area filter
+  # (?area=slug) once two areas have published entries. Manage areas in the admin ("Areas"): rename, reorder,
+  # merge, delete, and "Detect areas" to backfill entries that have none (it reuses config.rewriter).
+  # Entries you set by hand on the edit page are never changed by the AI.
+  # config.max_areas = 8
+
+  # Screenshots in entries. They need Active Storage in your app (require "active_storage/engine", and its tables);
+  # without it they stay off and Shiplog logs that once at boot. When a draft is written, the images in the GitHub
+  # issue or pull request body are attached to the entry (GitHub image hosts only, 5 MB and PNG, JPEG, GIF or
+  # WebP at most; the token needs no extra permission). You can also upload images on the entry edit page.
+  # config.images = true
+  # config.max_images_per_entry = 4
+
+  # Translations of entries. Entries are translated into each of these locales with config.rewriter when they are
+  # approved, and again when the English title or body of an approved entry changes; the translation is published
+  # at once, with no second approval. One LLM call per entry, locale and change. Admins can edit a translation on
+  # the entry page (kept until the English text changes) or retranslate it. Pages render the translation when
+  # I18n.locale is one of these and it matches the current English text, and English otherwise. Your routes
+  # decide which URLs set the locale (e.g. a /es scope). The default locale is dropped from the list.
+  # config.locales = []   # e.g. [:es]
+
   # Callables above cannot be part of the public pages' ETag. Bump this when the output of a callable you
   # configured changes (a new label, another path) so cached pages are refreshed.
   # config.cache_version = nil

data/lib/shiplog/classes.rb

@@ -49,7 +49,16 @@ module Shiplog
       search_button: "shiplog-search__button",
       search_summary: "shiplog-search__summary",
       search_clear: "shiplog-search__clear",
-      search_empty: "shiplog-search__empty"
+      search_empty: "shiplog-search__empty",
+      permalink: "shiplog-permalink",
+      permalink_back: "shiplog-permalink__back",
+      permalink_nav: "shiplog-permalink__nav",
+      permalink_nav_link: "shiplog-permalink__nav-link",
+      areas: "shiplog-areas",
+      area_link: "shiplog-areas__link",
+      entry_area: "shiplog-entry__area",
+      entry_images: "shiplog-entry__images",
+      entry_image: "shiplog-entry__image"
     }.freeze
 
     KEYS = BEM.keys.freeze

data/lib/shiplog/configuration.rb

@@ -5,7 +5,7 @@ module Shiplog
       :rewriter, :product_name, :audience, :tone, :prompt_builder,
       :public_layout, :admin_layout,
       :stylesheet, :admin_flash, :authorize_admin, :current_admin,
-      :roadmap_path, :changelog_path
+      :roadmap_path
 
     ADMIN_CHROMES = %i[standalone hosted].freeze
     # Segments of only dots ("." and "..") are path traversal, not names.
@@ -16,16 +16,47 @@ module Shiplog
     # Path of the lockfile read in merged pull requests to detect gem upgrades (see config.repositories `gem:`).
     attr_accessor :lockfile_path
 
+    # The public changelog's path: segments of a-z, 0-9, dashes and underscores, joined by slashes ("changelog",
+    # "docs/whats_new"); surrounding slashes are stripped. Permalinks live below it and the Atom feed is
+    # "<path>.atom". Read when routes are drawn.
+    attr_reader :changelog_path
+    CHANGELOG_PATH = %r{\A[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*\z}
+
+    # The site's canonical origin, e.g. "https://trackberry.com" (nil by default). When set, the Atom feed's ids
+    # and links, entry links, og:url and the other absolute URLs use it instead of the request's host, which
+    # varies (apex and www, a forged X-Forwarded-Host). An origin only: scheme, host and optional port. Any path
+    # prefix of the engine's mount comes from the routes, so it needs no place here.
+    attr_reader :canonical_url
+
     attr_reader :admin_chrome, :classes, :public_parent_controller, :admin_parent_controller
 
     # Product updates navigation and roadmap options.
     attr_accessor :feedback_path
     # Whether the public changelog has a search box and honours ?q= (default true).
     attr_accessor :changelog_search
+    # Whether the public pages carry schema.org JSON-LD (rendered by shiplog_head_tags; default true).
+    attr_accessor :structured_data
+    # The image shared with a permalink page when the entry has no screenshot: nil (default) or a callable
+    # `->(entry, locale) { "https://cdn.example.com/card.png" }` evaluated in the view (instance_exec, so
+    # `main_app` route helpers work). A path is made absolute with canonical_url or the request's origin; an
+    # error or a non-http(s) value is logged and the page renders without the image. See shiplog_head_tags.
+    attr_reader :og_image
+    # Called with the controller on each changelog index or permalink view (200 or 304 answers), e.g. to stamp
+    # the visitor's "last seen" time. It runs BEFORE the page renders (so a badge in the same response is
+    # current), on every visit, and may write: keep it cheap, e.g. write only when the stored time is older than
+    # the newest entry. Nil by default. Not part of the ETag: it doesn't change the markup.
+    attr_reader :on_changelog_seen
     # Bump it when the output of a callable you configured changes (extra_pages, repository_labels, feedback_path):
     # callables cannot be part of the ETag, so this is how cached public pages learn about it.
     attr_accessor :cache_version
     attr_reader :extra_pages, :repository_labels, :roadmap_shipped_count
+    # How many product areas the AI may create (default 8). Past it, entries can only join existing areas.
+    # Not part of render_digest: the markup depends on the areas themselves, which the ETag carries.
+    attr_reader :max_areas
+    # Screenshots in entries. `images` (default true) is effective only when Active Storage is loaded in the host
+    # (see Shiplog.images?). `max_images_per_entry` (default 4) caps the images fetched from GitHub per entry.
+    attr_reader :images, :max_images_per_entry
+    LOCALE_FORMAT = /\A[A-Za-z][A-Za-z0-9_-]*\z/
 
     EXTRA_PAGE_KEYS = %i[label path].freeze
 
@@ -43,10 +74,10 @@ module Shiplog
       stable = ->(value) { value.respond_to?(:call) ? "callable" : value }
       data = [
         classes.sort_by { |key, _| key.to_s }.map { |key, value| [ key.to_s, Array(value).map(&:to_s) ] },
-        stylesheet, roadmap_shipped_count, cache_version,
+        stylesheet, roadmap_shipped_count, cache_version, product_name, canonical_url,
         extra_pages.map { |page| [ stable.(page[:label]), stable.(page[:path]) ] },
         repository_labels.sort_by { |name, _| name.to_s }.map { |name, label| [ name, stable.(label) ] },
-        stable.(feedback_path), changelog_search
+        stable.(feedback_path), changelog_search, images, max_images_per_entry, locales, structured_data, stable.(og_image)
       ]
       Digest::SHA256.hexdigest(JSON.generate(data))
     end
@@ -92,6 +123,56 @@ module Shiplog
       @roadmap_shipped_count = value
     end
 
+    def max_areas=(value)
+      raise ArgumentError, "max_areas must be a non-negative Integer, got #{value.inspect}" unless value.is_a?(Integer) && value >= 0
+      @max_areas = value
+    end
+
+    def images=(value)
+      raise ArgumentError, "images must be true or false, got #{value.inspect}" unless [ true, false ].include?(value)
+      @images = value
+    end
+
+    def max_images_per_entry=(value)
+      raise ArgumentError, "max_images_per_entry must be a non-negative Integer, got #{value.inspect}" unless value.is_a?(Integer) && value >= 0
+      @max_images_per_entry = value
+    end
+
+    # Locales entries are translated into when approved, e.g. [:es] (default none), as symbols and without the
+    # default locale (I18n.default_locale, read each time so an initializer that sets it later still counts): it
+    # is the language entries are written in. See Shiplog::Translator.
+    def locales = @locales - [ I18n.default_locale.to_sym ]
+
+    # Sets the locales to translate into: an Array of locale Symbols or Strings (see #locales).
+    def locales=(value)
+      unless value.is_a?(Array) && value.all? { |item| (item.is_a?(Symbol) || item.is_a?(String)) && LOCALE_FORMAT.match?(item.to_s) }
+        raise ArgumentError, "locales must be an Array of locale Symbols or Strings like [:es, \"pt-BR\"], got #{value.inspect}"
+      end
+      @locales = value.map(&:to_sym).uniq.freeze
+    end
+
+    def changelog_path=(value)
+      path = value.gsub(%r{\A/+|/+\z}, "") if value.is_a?(String)
+      unless path && CHANGELOG_PATH.match?(path)
+        raise ArgumentError, "changelog_path must be a path of letters, digits, dashes and underscores, with / between segments (like \"changelog\"), got #{value.inspect}"
+      end
+      @changelog_path = path
+    end
+
+    def canonical_url=(value)
+      @canonical_url = normalize_canonical_url(value)
+    end
+
+    def og_image=(value)
+      raise ArgumentError, "og_image must be nil or a callable like ->(entry, locale) { url }, got #{value.inspect}" unless value.nil? || value.respond_to?(:call)
+      @og_image = value
+    end
+
+    def on_changelog_seen=(value)
+      raise ArgumentError, "on_changelog_seen must be nil or a callable, got #{value.inspect}" unless value.nil? || value.respond_to?(:call)
+      @on_changelog_seen = value
+    end
+
     # :standalone (default) wraps the admin in Shiplog's own page chrome; :hosted renders it inside the
     # layout of config.admin_layout (compact sub-nav, no page chrome of its own).
     def admin_chrome=(value)
@@ -158,6 +239,11 @@ module Shiplog
       @repository_labels = {}.freeze
       @roadmap_shipped_count = 4
       @changelog_search = true
+      @structured_data = true
+      @max_areas = 8
+      @images = true
+      @max_images_per_entry = 4
+      @locales = [].freeze
     end
 
     def resolved_github_token
@@ -196,6 +282,22 @@ module Shiplog
 
     private
 
+    def normalize_canonical_url(value)
+      return if value.nil? || (value.is_a?(String) && value.strip.empty?)
+      raise ArgumentError, "canonical_url must be a String like \"https://example.com\", got #{value.inspect}" unless value.is_a?(String)
+
+      uri = begin
+        URI.parse(value.strip)
+      rescue URI::InvalidURIError
+        nil
+      end
+      valid = uri.is_a?(URI::HTTP) && uri.host.present? && [ "", "/" ].include?(uri.path) && uri.query.nil? && uri.fragment.nil? && uri.userinfo.nil?
+      raise ArgumentError, "canonical_url must be an http(s) origin without path, query or credentials (\"https://example.com\"), got #{value.inspect}" unless valid
+
+      port = ":#{uri.port}" unless uri.port == uri.default_port
+      "#{uri.scheme}://#{uri.host.downcase}#{port}"
+    end
+
     def normalize_repositories(value)
       raise ArgumentError, "config.repositories must be an Array, got #{value.inspect}" unless value.is_a?(Array)
 

data/lib/shiplog/engine.rb

@@ -1,5 +1,13 @@
 module Shiplog
   class Engine < ::Rails::Engine
     isolate_namespace Shiplog
+
+    # shiplog_head_tags in every view, so a layout shared with the host's own pages can call it.
+    initializer "shiplog.head_tags_helper" do
+      ActiveSupport.on_load(:action_view) { include Shiplog::HeadTagsHelper }
+    end
+
+    # Once per boot, after the host's initializers have set config.images: say why screenshots are off.
+    config.after_initialize { Shiplog.log_images_status }
   end
 end

data/lib/shiplog/github/queries.rb

@@ -133,7 +133,19 @@ module Shiplog
         }
       GRAPHQL
 
-      ALL = { ISSUES:, PULL_REQUESTS:, ISSUE:, PULL_REQUEST:, COMMITS:, BLOB_TEXT:, COMMIT_PULL_REQUESTS: }.freeze
+      # The rendered HTML of one issue or pull request body (`$id` is its node id). Kept out of the sync documents so
+      # their payloads don't grow: it is only asked for when a draft is written, to find screenshots. On private
+      # repositories its <img src> URLs are short-lived signed URLs.
+      BODY_HTML = <<~GRAPHQL.freeze
+        query($id: ID!) {
+          node(id: $id) {
+            ... on Issue { bodyHTML }
+            ... on PullRequest { bodyHTML }
+          }
+        }
+      GRAPHQL
+
+      ALL = { ISSUES:, PULL_REQUESTS:, ISSUE:, PULL_REQUEST:, COMMITS:, BLOB_TEXT:, COMMIT_PULL_REQUESTS:, BODY_HTML: }.freeze
     end
   end
 end

data/lib/shiplog/version.rb

@@ -1,3 +1,3 @@
 module Shiplog
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end