plum-cms 0.2.3 → 0.3.0

data/app/services/plum/config_sync.rb

@@ -109,6 +109,7 @@ module Plum
         record.name = config["name"]
         record.icon = config["icon"]
         record.singleton = config["singleton"] unless config["singleton"].nil?
+        record.comments_enabled = config["comments_enabled"] unless config["comments_enabled"].nil?
         record.blueprint = merged_blueprint(record, config)
         track(result, record, file)
       end
@@ -207,6 +208,7 @@ module Plum
           "handle" => config["handle"].to_s,
           "icon" => config["icon"].presence,
           "singleton" => !!config["singleton"],
+          "comments_enabled" => !!config["comments_enabled"],
           "route_prefix" => config["route_prefix"].presence,
           "fields" => config["fields"] || []
         }
@@ -225,6 +227,7 @@ module Plum
         "handle" => record.handle,
         "icon" => record.icon,
         "singleton" => record.singleton,
+        "comments_enabled" => record.comments_enabled,
         "route_prefix" => record.route_prefix,
         "fields" => record.fields
       }

data/app/services/plum/liquid_context.rb

@@ -24,6 +24,11 @@ module Plum
       }.compact.merge(Plum.content_sources_for(controller, site: site))
     end
 
+    # Shared layout data without exposing the site's other entries or host sources.
+    def layout_context
+      { "site" => site_context, "globals" => globals_context, "nav" => nav_context, "forms" => forms_context }
+    end
+
     private
 
     attr_reader :controller, :site, :entry, :theme_name, :theme_settings
@@ -60,6 +65,9 @@ module Plum
         "url" => public_entry_path(entry),
         "data" => entry_data_context(entry, relationship_depth: relationship_depth, expand_blocks: expand_blocks)
       }
+      if Plum.configuration.comments.enabled && entry.plum_comments_enabled?
+        ctx["discussion_url"] = "#{controller.request.script_name.to_s.chomp('/')}/discussions/entries/#{entry.id}"
+      end
       if entry.association(:terms).loaded? && entry.terms.any?
         ctx["terms"] = entry.terms.group_by { |t| t.taxonomy.handle }.transform_values do |terms|
           terms.map { |t| { "name" => t.name, "slug" => t.slug, "url" => "/#{t.taxonomy.slug}/#{t.slug}" } }

data/app/services/plum/liquid_renderer.rb

@@ -30,6 +30,14 @@ module Plum
         end
       end
 
+      # Render a theme fragment through the same inheritance and filter pipeline.
+      def render_partial(template_name, context = {})
+        path = ThemeResolver.new.find_template(current_theme(context), template_name)
+        raise "Template not found: #{template_name}" unless path
+
+        Liquid::Template.parse(File.read(path)).render(context, filters: [ LiquidFilters ], registers: render_registers(context))
+      end
+
       private
 
       def current_theme(context)

data/app/services/plum/site_archive.rb

@@ -56,7 +56,7 @@ module Plum
           "exported_at" => Time.current.iso8601,
           "site" => record(site, %w[id name domain theme_name settings theme_settings custom_css]),
           "site_setting" => site.site_setting && record(site.site_setting, site_setting_fields),
-          "content_types" => records(site.content_types, %w[id name handle singleton blueprint icon]),
+          "content_types" => records(site.content_types, %w[id name handle singleton blueprint icon comments_enabled]),
           "fieldsets" => records(site.fieldsets, %w[id name handle fields]),
           "taxonomies" => records(site.taxonomies, %w[id name handle slug]),
           "terms" => records(site.terms, %w[id taxonomy_id name slug position]),
@@ -76,7 +76,7 @@ module Plum
       end
 
       def entry_record(entry)
-        record(entry, %w[id content_type_id title slug status data published_at author_name author_email author_gid locale origin_id]).merge(
+        record(entry, %w[id content_type_id title slug status data published_at author_name author_email author_gid locale origin_id comments_mode]).merge(
           "term_ids" => entry.term_ids
         )
       end
@@ -167,7 +167,7 @@ module Plum
         )
         maps[:sites][source["id"]] = @site.id
 
-        import_simple(:content_types, ContentType, %w[name handle singleton blueprint icon])
+        import_simple(:content_types, ContentType, %w[name handle singleton blueprint icon comments_enabled])
         import_simple(:fieldsets, Fieldset, %w[name handle fields])
         import_simple(:taxonomies, Taxonomy, %w[name handle slug])
         import_terms
@@ -239,7 +239,7 @@ module Plum
 
       def import_entries
         Array(data["entries"]).each do |source|
-          entry = Entry.create!(source.slice("title", "slug", "status", "data", "published_at", "author_name", "author_email", "author_gid", "locale").merge(
+          entry = Entry.create!(source.slice("title", "slug", "status", "data", "published_at", "author_name", "author_email", "author_gid", "locale", "comments_mode").merge(
             "site_id" => @site.id,
             "content_type_id" => mapped!(:content_types, source["content_type_id"])
           ))

data/app/themes/default/layouts/base.liquid

@@ -3,7 +3,7 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>{{ entry.title | default: site.seo_title | default: site.name }} - {{ site.name }}</title>
+  <title>{{ discussion.title | default: entry.title | default: site.seo_title | default: site.name }} - {{ site.name }}</title>
   <meta name="description" content="{{ site.seo_description }}">
   <link rel="icon" href="/icon.svg" type="image/svg+xml">
   <link rel="stylesheet" href="{{ 'theme.css' | theme_asset_url }}">

data/app/themes/default/templates/comments/_comment.liquid

@@ -0,0 +1,8 @@
+<article id="comment-{{ comment.id }}" class="plum-comment">
+<header><strong>{{ comment.author_name }}</strong> {% if comment.author_badge != blank %}<span>{{ comment.author_badge }}</span>{% endif %} <time datetime="{{ comment.created_at }}">{{ comment.date }}</time> {% if comment.pinned %}Pinned{% endif %}</header>
+{% if comment.parent_id %}<p>In reply to {{ comment.parent_author_name }}</p>{% endif %}
+{% if comment.video_seconds %}<p>At {{ comment.video_time }}</p>{% endif %}
+<p class="plum-comment-body">{{ comment.body }}</p>
+{% if comment.reply_form_html %}<details><summary>Reply</summary>{{ comment.reply_form_html }}</details>{% endif %}
+{% if comment.report_form_html %}<details><summary>Report</summary>{{ comment.report_form_html }}</details>{% endif %}
+</article>

data/app/themes/default/templates/comments/_form.liquid

@@ -0,0 +1,7 @@
+<form method="post" action="{{ discussion.post_url }}" class="plum-comment-form">
+<input type="hidden" name="authenticity_token" value="{{ discussion.csrf_token }}">
+{% if form.parent_id %}<input type="hidden" name="comment[parent_id]" value="{{ form.parent_id }}">{% endif %}
+<label for="comment-body-{{ form.id }}">{% if form.parent_id %}Your reply{% else %}Your comment{% endif %}</label>
+<textarea id="comment-body-{{ form.id }}" name="comment[body]" maxlength="10000" rows="4" required></textarea>
+<button type="submit">{% if form.parent_id %}Send reply{% else %}Send comment{% endif %}</button>
+</form>

data/app/themes/default/templates/comments/_report.liquid

@@ -0,0 +1,6 @@
+<form method="post" action="{{ comment.report_url }}" class="plum-comment-report-form">
+<input type="hidden" name="authenticity_token" value="{{ discussion.csrf_token }}">
+<label for="report-reason-{{ comment.id }}">Reason for reporting</label>
+<textarea id="report-reason-{{ comment.id }}" name="report[reason]" maxlength="1000" required></textarea>
+<button type="submit">Send report</button>
+</form>

data/app/themes/default/templates/comments/show.liquid

@@ -0,0 +1,15 @@
+<link rel="stylesheet" href="{{ discussion.stylesheet_url }}">
+<section class="plum-discussion" aria-labelledby="discussion-title">
+{% for notice in discussion.notices %}<p role="status">{{ notice }}</p>{% endfor %}
+{% if discussion.back_url != blank %}<a href="{{ discussion.back_url }}">Back to {{ discussion.title }}</a>{% endif %}
+<h1 id="discussion-title">{{ discussion.title }}</h1>
+<h2>Questions &amp; discussion</h2>
+<p>Ask a question, share a reflection, or join the conversation. Please be kind and stay on topic. Comments may be reviewed before appearing.</p>
+{% if discussion.comments == empty %}<p>No comments to show yet.</p>{% endif %}
+{{ discussion.comments_html }}
+<nav aria-label="Discussion pages">{% if discussion.previous_url %}<a href="{{ discussion.previous_url }}">Previous</a>{% endif %}{% if discussion.next_url %}<a href="{{ discussion.next_url }}">Next</a>{% endif %}</nav>
+{% if discussion.open == false %}<p>This discussion is closed to new comments.</p>
+{% elsif discussion.signed_in %}{{ discussion.form_html }}
+{% else %}<p>Sign in to join the discussion.</p>{% if discussion.login_url != blank %}<a href="{{ discussion.login_url }}">Sign in</a>{% endif %}
+{% endif %}
+</section>

data/app/themes/default/templates/entries/_default.liquid

@@ -23,4 +23,5 @@
     <p><em>{{ entry.data.excerpt }}</em></p>
   </div>
   {% endif %}
+  {% if entry.discussion_url %}<p class="plum-discussion-link"><a href="{{ entry.discussion_url }}">Questions &amp; discussion →</a></p>{% endif %}
 </article>

data/app/themes/default/templates/entries/landing.liquid

@@ -2,4 +2,5 @@
   <h1>{{ entry.title }}</h1>
 
   {{ entry.data.sections }}
+  {% if entry.discussion_url %}<p class="plum-discussion-link"><a href="{{ entry.discussion_url }}">Questions &amp; discussion →</a></p>{% endif %}
 </article>

data/app/themes/default/templates/entries/pages.liquid

@@ -14,4 +14,5 @@
   {% if sections_html != "" %}
     {{ sections_html }}
   {% endif %}
+  {% if entry.discussion_url %}<p class="plum-discussion-link"><a href="{{ entry.discussion_url }}">Questions &amp; discussion →</a></p>{% endif %}
 </article>

data/app/themes/default/templates/entries/posts.liquid

@@ -17,4 +17,5 @@
     <p><strong>Summary:</strong> {{ entry.data.excerpt }}</p>
   </aside>
   {% endif %}
+  {% if entry.discussion_url %}<p class="plum-discussion-link"><a href="{{ entry.discussion_url }}">Questions &amp; discussion →</a></p>{% endif %}
 </article>

data/app/views/layouts/plum/cp.html.erb

@@ -88,6 +88,9 @@
                 class: "flex items-center px-4 py-2 mt-2 text-sm font-medium rounded-md plum-sidebar-link #{request.path.include?('/cp/nav_menus') ? 'active' : ''}" %>
             <%= link_to "Taxonomies", "#{cp_prefix}/taxonomies",
                 class: "flex items-center px-4 py-2 mt-2 text-sm font-medium rounded-md plum-sidebar-link #{request.path.include?('/taxonomies') ? 'active' : ''}" %>
+            <% if Plum.configuration.comments.enabled && Plum.configuration.comments.moderator_resolver.call(controller, current_site) %>
+              <%= link_to "Comments", cp_comments_path, class: "flex items-center px-4 py-2 mt-2 text-sm font-medium rounded-md plum-sidebar-link" %>
+            <% end %>
             <%= link_to "Forms", cp_form_definitions_path,
                 class: "flex items-center px-4 py-2 mt-2 text-sm font-medium rounded-md plum-sidebar-link #{request.path.include?('/cp/forms') ? 'active' : ''}" %>
           </div>

data/app/views/layouts/plum/discussion.html.erb

@@ -0,0 +1,5 @@
+<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Discussion</title><%= csrf_meta_tags %><%= stylesheet_link_tag "plum/comments" %></head>
+<body><main class="plum-discussion"><% flash.each do |_kind, message| %><p role="status"><%= message %></p><% end %><%= yield %></main></body>
+</html>

data/app/views/plum/cp/comments/index.html.erb

@@ -0,0 +1,16 @@
+<h1 class="text-2xl font-bold mb-4">Comments</h1>
+<nav class="flex gap-4 mb-6"><% %w[pending approved hidden reported].each do |status| %><%= link_to status.titleize, cp_comments_path(status: status), class: "underline" %><% end %></nav>
+<% if @comments.empty? %><p>No comments in this view.</p><% end %>
+<% @comments.each do |comment| %>
+<article class="border rounded p-4 mb-4">
+<h2 class="font-bold"><%= comment.discussion.commentable&.plum_discussion_title %></h2>
+<p><%= comment.author_name %> · <%= comment.status %> · <%= comment.created_at.to_fs(:short) %></p>
+<p class="whitespace-pre-wrap my-4"><%= comment.body %></p>
+<% comment.reports.where(resolved_at: nil).each do |report| %><p>Report: <%= report.reason %></p><% end %>
+<div class="flex gap-4 flex-wrap"><% %w[approve hide pin unpin resolve_reports].each do |operation| %><% next if operation == "pin" && comment.parent_id.present? %><%= button_to operation.humanize, cp_comment_path(comment), method: :patch, params: { operation: operation }, class: "underline" %><% end %>
+<%= button_to comment.discussion.closed? ? "Reopen discussion" : "Close discussion", cp_close_discussion_path(comment.discussion), method: :patch, params: { closed: !comment.discussion.closed? }, class: "underline" %></div>
+</article>
+<% end %>
+<% current_page = params[:page].to_i.clamp(1, 10000) %>
+<%= link_to "Previous", cp_comments_path(status: @status, page: current_page - 1) if current_page > 1 %>
+<%= link_to "Next", cp_comments_path(status: @status, page: current_page + 1) %>

data/app/views/plum/cp/content_types/_form.html.erb

@@ -9,6 +9,9 @@
     </div>
   <% end %>
 
+  <% if Plum.configuration.comments.enabled %>
+    <div><%= f.check_box :comments_enabled %> <%= f.label :comments_enabled, "Enable comments by default for this content type" %></div>
+  <% end %>
   <div class="bg-white shadow rounded-lg p-6 space-y-6">
     <div>
       <%= f.label :name, class: "block text-sm font-medium text-gray-700" %>

data/app/views/plum/cp/entries/_form.html.erb

@@ -10,6 +10,9 @@
       </div>
     <% end %>
 
+    <% if Plum.configuration.comments.enabled %>
+      <div><%= f.label :comments_mode, "Discussion" %> <%= f.select :comments_mode, [["Use content type setting", "inherit"], ["Open", "open"], ["Closed (existing comments remain visible)", "closed"], ["Disabled (hide discussion)", "disabled"]] %></div>
+    <% end %>
     <div class="grid grid-cols-1 lg:grid-cols-3 gap-6" style="align-items: start;">
       <!-- Main content -->
       <div class="lg:col-span-2 space-y-6">

data/app/views/plum/discussions/_comments.html.erb

@@ -0,0 +1,13 @@
+<% if comments.empty? %><p>No comments to show yet.</p><% end %>
+<% comments.each do |comment| %>
+<article id="comment-<%= comment.id %>" class="plum-comment">
+<header><strong><%= comment.author_name %></strong> <% if comment.author_badge.present? %><span><%= comment.author_badge %></span><% end %> <time datetime="<%= comment.created_at.iso8601 %>"><%= comment.created_at.to_date.to_fs(:long) %></time> <%= "Pinned" if comment.pinned? %></header>
+<% if comment.parent %><p>In reply to <%= comment.parent.author_name %></p><% end %>
+<% if comment.video_seconds %><p>At <%= comment.video_seconds / 60 %>:<%= "%02d" % (comment.video_seconds % 60) %></p><% end %>
+<p class="plum-comment-body"><%= comment.body %></p>
+<% if context.author_gid %>
+<% if context.open? && comment.parent_id.nil? %><details><summary>Reply</summary><%= render "plum/discussions/form", context: context, parent: comment %></details><% end %>
+<details><summary>Report</summary><%= form_with url: report_discussion_comment_path(handle: context.handle, subject_id: context.subject.id, id: comment.id), scope: :report do |form| %><%= form.label :reason, "Reason for reporting", for: "report-reason-#{comment.id}" %><%= form.text_area :reason, id: "report-reason-#{comment.id}", required: true, maxlength: 1000 %><%= form.submit "Send report" %><% end %></details>
+<% end %>
+</article>
+<% end %>

data/app/views/plum/discussions/_form.html.erb

@@ -0,0 +1,6 @@
+<%= form_with url: discussion_comments_path(handle: context.handle, subject_id: context.subject.id), scope: :comment do |form| %>
+<% if parent %><%= form.hidden_field :parent_id, value: parent.id %><% end %>
+<%= form.label :body, parent ? "Your reply" : "Your comment", for: "comment-body-#{parent&.id || 'new'}" %>
+<%= form.text_area :body, required: true, maxlength: 10000, rows: 4, id: "comment-body-#{parent&.id || 'new'}" %>
+<%= form.submit parent ? "Send reply" : "Send comment" %>
+<% end %>

data/app/views/plum/discussions/show.html.erb

@@ -0,0 +1,19 @@
+<% back_url = @context.config.subject_url_resolver.call(self.controller, @context.subject) %>
+<% if back_url.present? %><%= link_to "Back to #{@context.subject.plum_discussion_title}", back_url %><% end %>
+<h1><%= @context.subject.plum_discussion_title %></h1>
+<h2>Questions &amp; discussion</h2>
+<p>Ask a question, share a reflection, or join the conversation. Please be kind and stay on topic. Comments may be reviewed before appearing.</p>
+<%= render "plum/discussions/comments", context: @context, comments: @comments %>
+<nav aria-label="Discussion pages">
+<%= link_to "Previous", discussion_path(handle: @context.handle, subject_id: @context.subject.id, page: page - 1) if page > 1 %>
+<%= link_to "Next", discussion_path(handle: @context.handle, subject_id: @context.subject.id, page: page + 1) if @comments.size == 50 %>
+</nav>
+<% if !@context.open? %>
+<p>This discussion is closed to new comments.</p>
+<% elsif @context.author_gid %>
+<%= render "plum/discussions/form", context: @context, parent: nil %>
+<% else %>
+<p>Sign in to join the discussion.</p>
+<% login_url = @context.config.login_url_resolver.call(self.controller) %>
+<%= link_to "Sign in", login_url if login_url.present? %>
+<% end %>

data/config/plum_routes.rb

@@ -4,6 +4,8 @@ Plum::Engine.routes.draw do
   delete "logout", to: "sessions#destroy"
 
   namespace :cp do
+    resources :comments, only: [ :index, :update ]
+    patch "discussions/:id", to: "comments#close", as: :close_discussion
     root "dashboard#show"
     resources :content_types do
       post :apply_fieldset, on: :member
@@ -38,6 +40,10 @@ Plum::Engine.routes.draw do
     get "theme_previews/:handle", to: "theme_previews#show", as: :theme_preview
   end
 
+  get "discussions/:handle/:subject_id", to: "discussions#show", as: :discussion
+  post "discussions/:handle/:subject_id/comments", to: "discussions#create", as: :discussion_comments
+  post "discussions/:handle/:subject_id/comments/:id/report", to: "discussions#report", as: :report_discussion_comment
+
   post "forms/:handle", to: "form_submissions#create", as: :form
   namespace :api do
     namespace :v1 do

data/db/engine_migrate/20261005190000_create_plum_comments.rb

@@ -0,0 +1,48 @@
+class CreatePlumComments < ActiveRecord::Migration[8.0]
+  def change
+    add_column :plum_content_types, :comments_enabled, :boolean, default: false, null: false
+    add_column :plum_entries, :comments_mode, :string, default: "inherit", null: false
+
+    create_table :plum_discussions do |t|
+      t.references :site, null: false, foreign_key: { to_table: :plum_sites }
+      t.string :commentable_type, null: false
+      t.string :commentable_id, null: false
+      t.string :subject_handle, null: false
+      t.boolean :closed, null: false, default: false
+      t.timestamps
+    end
+    add_index :plum_discussions, [ :site_id, :commentable_type, :commentable_id ], unique: true, name: "plum_discussion_subject_unique"
+
+    create_table :plum_comments do |t|
+      t.references :discussion, null: false, foreign_key: { to_table: :plum_discussions }
+      t.references :parent, foreign_key: { to_table: :plum_comments }
+      t.string :author_gid, null: false
+      t.string :author_name, null: false
+      t.string :author_badge
+      t.text :body, null: false
+      t.string :status, null: false, default: "pending"
+      t.boolean :pinned, null: false, default: false
+      t.integer :video_seconds
+      t.timestamps
+    end
+    add_index :plum_comments, [ :discussion_id, :status, :id ]
+    add_index :plum_comments, [ :author_gid, :created_at ]
+
+    create_table :plum_comment_reports do |t|
+      t.references :comment, null: false, foreign_key: { to_table: :plum_comments }
+      t.string :reporter_gid, null: false
+      t.text :reason, null: false
+      t.datetime :resolved_at
+      t.timestamps
+    end
+    add_index :plum_comment_reports, [ :comment_id, :reporter_gid ], unique: true
+
+    create_table :plum_comment_moderations do |t|
+      t.references :comment, null: false, foreign_key: { to_table: :plum_comments }
+      t.string :moderator_gid, null: false
+      t.string :action, null: false
+      t.string :previous_status, null: false
+      t.timestamps
+    end
+  end
+end

data/docs/comments.md

@@ -0,0 +1,140 @@
+# Comments and discussions
+
+Plum 0.3 adds optional discussions for CMS entries and application models. The feature is off by default. The new engine migration is required on every upgrade to 0.3.0, even if comments remain disabled:
+
+```sh
+bin/rails plum:install:migrations
+bin/rails db:migrate
+```
+
+## Enable and connect authentication
+
+```ruby
+Plum.configure do |config|
+  config.comments.enabled = true
+  # A persisted, GlobalID-compatible account, authenticated by YOUR application.
+  # Check email verification, suspension, membership, etc. here as appropriate.
+  config.comments.commenter_resolver = ->(controller) {
+    user = controller.current_reader
+    user if user&.email_verified? && !user.suspended?
+  }
+  config.comments.author_name_resolver = ->(user) { user.display_name }
+  config.comments.login_url_resolver = ->(controller) { controller.main_app.new_session_path }
+  config.comments.subject_url_resolver = ->(controller, subject) {
+    controller.main_app.lesson_path(subject.slug)
+  }
+end
+```
+
+Reader authentication is independent of `Plum.current_user` and never grants CMS access. By default there is no commenter, names display as “Reader,” no badge is added, and new comments require approval. The host must supply a verified account, a safe public display name, and any additional account/IP abuse protection. The built-in write limit is one comment per reader per discussion every ten seconds; it is not a global anti-spam service.
+
+Enable comments on a content type in the control panel, or set `comments_enabled: true` on `Plum::ContentType`. Each entry has a `comments_mode`: `inherit`, `open`, `closed` (readable), or `disabled` (hidden). Unpublished/future entries are never publicly accessible through the built-in entry endpoint. Closing a discussion stops new comments and replies; reports remain possible.
+
+For restricted content, configure **all** relevant actions. Read authorization is also required for creating and reporting. Moderator authorization deliberately can include unpublished content:
+
+```ruby
+config.comments.entry_authorizer = ->(controller, action, entry) {
+  action == :moderate ? controller.can_moderate?(entry) : controller.can_read?(entry)
+}
+```
+
+The callbacks receive `:read`, `:create`, `:report`, or `:moderate`. Enforce parent course visibility, enrollment, paid access, and group membership here: a published lesson alone does not prove access to its course. Site membership is independently checked on every request.
+
+## Application models
+
+```ruby
+class Lesson < ApplicationRecord
+  include Plum::Commentable
+  belongs_to :site, class_name: "Plum::Site"
+
+  # Override these methods when your schema differs:
+  def plum_comment_site = site
+  def plum_discussion_title = title
+  def plum_comments_enabled? = published?
+  def plum_comments_open? = published? && !archived?
+end
+
+Plum.configure do |config|
+  config.comments.register :lessons,
+    resolve: ->(controller, site, id) { Lesson.where(site: site).find(id) },
+    authorize: ->(controller, action, lesson) { controller.allowed?(action, lesson) }
+end
+```
+
+Registration is required. Request parameters never choose arbitrary model classes or resolve arbitrary GlobalIDs. Integer and UUID subject IDs are supported. Each subject has one discussion, with dependent cleanup when the subject is destroyed. Register a single stable handle per model; changing handles requires migrating existing discussion `subject_handle` values. `entries` is reserved for Plum entries.
+
+## Rendering
+
+By default, discussions render inside the active Plum theme's `layouts/base.liquid`, inheriting the same theme settings, custom CSS, fonts and colors. Override any of these files in your theme:
+
+```
+templates/comments/show.liquid
+templates/comments/_comment.liquid
+templates/comments/_form.liquid
+templates/comments/_report.liquid
+```
+
+Liquid entry templates receive `entry.discussion_url` when comments are enabled for that entry. The bundled entry templates display a link automatically. Custom themes can use:
+
+```liquid
+{% if entry.discussion_url %}
+  <a href="{{ entry.discussion_url }}">Questions &amp; discussion</a>
+{% endif %}
+```
+
+This link is safe in static content; authorization and personalized forms are evaluated on the dynamic discussion page.
+
+Normal parent-theme inheritance applies to each template independently, then falls back to the bundled default. You can change the page structure, form layout, empty state, sign-in prompt, wording and styling without changing the gem. The discussion controller still enforces authorization, CSRF, validation and moderation.
+
+`discussion` includes `title`, `open`, `signed_in`, `back_url`, `login_url`, `previous_url`, `next_url`, `notices`, `stylesheet_url`, `comments`, `comments_html`, and `form_html`. Each approved comment includes `id`, `body`, `author_name`, `author_badge`, `date`, `created_at`, `parent_id`, `parent_author_name`, `pinned`, `video_seconds`, `video_time`, `reply_form_html`, and `report_form_html`. User-supplied text is **already HTML escaped** before entering Liquid: output it directly as `{{ comment.body }}`, without `escape` or decoding it. The HTML fragments are rendered from the theme's partials. No author account IDs, report details or unpublished comment bodies are exposed.
+
+Custom forms must retain the hidden `authenticity_token` with `discussion.csrf_token`, `method="post"`, and the supplied `discussion.post_url` or `comment.report_url`. Field names are `comment[body]`, optional `comment[parent_id]`/`comment[video_seconds]`, and `report[reason]`. Form partials receive `form.id` and `form.parent_id`. Themes can style the stable `.plum-discussion`, `.plum-comment`, `.plum-comment-body`, `.plum-comment-form`, and `.plum-comment-report-form` classes. The baseline CSS inherits fonts/colors and exposes `--plum-comment-border`, `--plum-discussion-title-size`, `--plum-comment-button-background`, and `--plum-comment-button-color` variables. Override the page template to omit the baseline stylesheet entirely.
+
+For an application such as Redeemer that renders its public site in Rails ERB, use `config.comments.renderer = :rails`. Override the engine's ERB views/layout in the host (see below) to reuse that application's design system.
+
+In a dynamic host Rails view, include `Plum::CommentsHelper` in the host helper module, then:
+
+```erb
+<%= plum_comments_link(@entry) %>
+<%= plum_comments_link(@lesson, handle: "lessons", label: "Ask a question") %>
+```
+
+Links open the engine's accessible discussion page, with forms, one level of replies, pagination, pinned comments and reporting. No JavaScript dependency is required. Replies to hidden/pending parents are hidden too. Bodies are plain text, escaped on output, and limited to 10,000 characters. Optional `comment[video_seconds]` stores a nonnegative integer timestamp (up to seven days); it does not synchronize YouTube comments.
+
+Override `app/views/layouts/plum/discussion.html.erb` or `app/views/plum/discussions/{show,_comments,_form}.html.erb` in the host for full branding. The default layout loads `plum/comments.css`. Controller paths and route helpers are engine scoped; use `plum.discussion_path(handle: "entries", subject_id: entry.id)` from a host. The helper uses the mounted engine route proxy.
+
+Do not put user-specific comment forms in Liquid/static page caches. Discussion responses use `private, no-store`; the default design links from cached content to a dynamic page. No comments are added to the public content API automatically.
+
+## Moderation
+
+The Comments control-panel queue supports pending/approved/hidden/reported views, approval, hiding/restoring, pinning, report resolution, and closing/reopening discussions. Comment moderation actions record actor GlobalID, action, previous status and timestamp. Discussion close/reopen changes are not part of that comment audit trail. A moderator must pass both normal CMS authorization and the separate comments moderator check. Entry/model authorization is applied to each record too.
+
+Plum-managed editor/admin accounts can moderate by default. Host-authenticated applications **must explicitly configure** the moderator callback; generic CMS access alone is insufficient:
+
+```ruby
+config.comments.moderator_resolver = ->(controller, site) {
+  controller.current_user.can_moderate_comments?(site)
+}
+```
+
+`Plum.current_user` must return a persisted GlobalID-compatible moderator for the audit trail. Optional trusted-author settings:
+
+```ruby
+config.comments.auto_approve = ->(controller, author, subject) { author.trusted? }
+config.comments.author_badge_resolver = ->(controller, author) { "Pastor" if author.pastor? }
+```
+
+Badges, authors and approval status are always assigned by server callbacks, never request parameters. Author name/badge are snapshots. Applications own policies for account deletion, pseudonyms, retention, and removal of historical display names. GlobalIDs are stored as references, not automatically dereferenced when rendering, so deleted accounts do not break threads.
+
+## Notifications and backups
+
+After commit, `comment.created.plum` and `comment.updated.plum` events carry `comment_id`, `discussion_id`, `site_id`, and `status`. Subscribe with `ActiveSupport::Notifications` and enqueue your own job or Noticed notification. Fetch the current record and re-check publication and recipient authorization before sending; never email pending/private comments to unauthorized readers. Subscribers should handle their own delivery failures and avoid synchronous mail delivery.
+
+```ruby
+ActiveSupport::Notifications.subscribe("comment.created.plum") do |*args|
+  payload = args.last
+  CommentModerationNotificationJob.perform_later(payload[:comment_id])
+end
+```
+
+Comments, reports and audit records are application data: include the `plum_discussions`, `plum_comments`, `plum_comment_reports` and `plum_comment_moderations` tables in database backups. Site archive/config exports include comment settings, **not conversations or account identities**. Replacing/deleting a site's content deletes its discussions, so take a database backup before archive replacement. A site archive alone is not a backup of community data.

data/docs/releases/0.3.0-validation.md

@@ -0,0 +1,15 @@
+# 0.3.0 release validation
+
+Validated October 5, 2026.
+
+- Ruby 3.3.1 / Rails 8.0.5: 238 tests, 950 assertions pass on SQLite and PostgreSQL.
+- Browser discussion lifecycle: posting, approval, public display and closing pass (10 assertions).
+- Redeemer mounted-engine consumer on Ruby 4.0.6 / Rails 8.1.3.1: 17 tests, 231 assertions pass. Mobile/desktop discussion pages render without overflow or JavaScript errors.
+- RuboCop: 227 files, no offenses. Importmap audit: no vulnerable versioned packages (Lexxy is unversioned and skipped by the audit).
+- Brakeman: seven existing findings outside comments; no new feature findings.
+- Full legacy CMS browser suite remains red. Failures in blueprint editing, writing mode, uploads and other existing CMS interactions were reproduced in a separate, unchanged 0.2.3 checkout. The new discussion browser test passes independently.
+- Engine/standalone migrations match. A fresh isolated database generated the committed schema; unrelated local analytics schema artifacts were removed. The built gem includes migrations, theme templates, controllers, helpers, styles and documentation.
+
+The owner requested independent review through the Claude CLI using `claude-fable-5-1`. Two read-only reviews were performed with that exact model. Initial findings about schema pollution and mandatory upgrade migrations were resolved. The follow-up reviewed theme inheritance, escaping, CSRF, authorization/context disclosure, assets and engine mounting and concluded: “no blockers found” and “0.3.0 is ready to publish.” Suggested polish for renderer configuration, page titles, inherited forms and nil predicates was implemented and tested afterward.
+
+Comments remain disabled by default. Database migration is required for every upgrade to 0.3.0. Reader authentication, notification delivery and account policy belong to the host application. Redeemer has branded discussion pages and moderation available, but public reader posting remains disabled until its member-account flow is implemented.

data/lib/plum/comments/configuration.rb

@@ -0,0 +1,43 @@
+module Plum
+  module Comments
+    class Configuration
+      attr_accessor :enabled, :commenter_resolver, :moderator_resolver,
+                    :author_name_resolver, :author_badge_resolver, :auto_approve,
+                    :entry_authorizer, :login_url_resolver, :subject_url_resolver
+      attr_reader :subjects, :renderer
+
+      def initialize
+        @enabled = false
+        @renderer = :theme
+        # Deliberately separate from CMS authentication. Hosts supply verified readers.
+        @commenter_resolver = ->(_controller) { nil }
+        @moderator_resolver = lambda { |controller, _site|
+          user = Plum.current_user(controller)
+          Plum.configuration.authorize_with == :plum && user.is_a?(Plum::User) && %w[editor admin].include?(user.role)
+        }
+        @author_name_resolver = ->(_author) { "Reader" }
+        @author_badge_resolver = ->(_controller, _author) { nil }
+        @auto_approve = ->(_controller, _author, _subject) { false }
+        @entry_authorizer = ->(_controller, _action, _entry) { true }
+        @login_url_resolver = ->(_controller) { nil }
+        @subject_url_resolver = ->(_controller, _subject) { nil }
+        @subjects = {}
+      end
+
+      def renderer=(value)
+        raise ArgumentError, "Comments renderer must be theme or rails" unless %w[theme rails].include?(value.to_s)
+        @renderer = value.to_sym
+      end
+
+      # The resolver must return a record from the host's authorized tenant scope.
+      # Neither a model class nor a GlobalID is accepted from the HTTP client.
+      def register(handle, resolve:, authorize:)
+        key = handle.to_s
+        unless key.match?(/\A[a-z][a-z0-9_]*\z/) && key != "entries"
+          raise ArgumentError, "Use a lowercase subject handle other than entries"
+        end
+        @subjects[key] = { resolve: resolve, authorize: authorize }
+      end
+    end
+  end
+end

data/lib/plum/configuration.rb

@@ -1,4 +1,5 @@
 require_relative "content_source_registry"
+require_relative "comments/configuration"
 
 module Plum
   class Configuration
@@ -9,7 +10,7 @@ module Plum
                   :powered_by_name, :powered_by_url,
                   :static_cache_enabled, :static_cache_path, :config_path
     attr_writer :theme_paths
-    attr_reader :content_sources
+    attr_reader :content_sources, :comments
 
     def initialize
       @authorize_with = :plum
@@ -37,6 +38,7 @@ module Plum
       # nil = default to Rails.root/plum when the tasks are invoked.
       @config_path = nil
       @content_sources = ContentSourceRegistry.new
+      @comments = Comments::Configuration.new
       @current_site_resolver = ->(_controller) { Plum::Site.first_or_create_standalone! }
       @current_user_resolver = lambda { |controller|
         Plum::User.find_by(id: controller.session[:plum_user_id]) if controller.session[:plum_user_id]

data/lib/plum/version.rb

@@ -1,6 +1,6 @@
 module Plum
   module Version
-    STRING = "0.2.3"
+    STRING = "0.3.0"
   end
 
   VERSION = Version::STRING