macron-cms 3.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 774dc3fc574e2fcd3d5e200b370bd6886718539fbab312cfe17632d1b18d153b
-  data.tar.gz: 003dbe77a32e518917f3f2c342319a27c701bad690d9a6acfbf009efaef91ce2
+  metadata.gz: d33f2ffc21a60f2fed407e0b1aac793f203a304203a6d58c0a5c87680e7d33e3
+  data.tar.gz: 27faeca2f7e1f4dc031e9786ec1739f19b59e2d088a0a7f7f5cdcc1f43bdb9b6
 SHA512:
-  metadata.gz: 75063868fbbbb013c613f307de1c6d790066eb146f9add543dbb3961df14f6ba98502a81a433e1adbd27bbd9304f774dac0dfc592564d92883b66bd7ea1e9b0a
-  data.tar.gz: 66ffde9ab34f2cf35255183e7a396f29db811100e858ee56aa6d85a1e565ab13dbe30f66d18e1ea61edfa82312b6bbb0b4d7ed25464674f2c1a0c3c882bbee05
+  metadata.gz: 16aabb8fa8b2be75dc01a49f0c5e2267d85266a2c80566d6730095e8300df6cdb544962a1184a07fae8632145893f9a6307395762a1e16396b6fabcb402fef4b
+  data.tar.gz: 8ce4de32d67626c86c5025bc78a07f1598a8cfc26d5ce3e980cf00581b8484b6976f0e9dfea91b8ea97f3df17c7542779c319151f186664256a9accdcc5c804d

data/README.md

@@ -1,7 +1,10 @@
 # MacronCMS
 
-[![Gem Version](https://img.shields.io/badge/version-3.0.0-emerald.svg)](#version)
+[![Gem Version](https://img.shields.io/badge/version-5.0.0-emerald.svg)](#version)
 [![Rails 8+](https://img.shields.io/badge/rails-8%2B-red.svg)](https://rubyonrails.org)
+[![React](https://img.shields.io/badge/React-20232A?logo=react&logoColor=61DAFB)](https://react.dev)
+[![Three.js](https://img.shields.io/badge/Three.js-black?logo=three.js&logoColor=white)](https://threejs.org)
+[![MCP Server](https://img.shields.io/badge/MCP-Server-purple.svg)](https://github.com/macron1-automations/macron-cms-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](MIT-LICENSE)
 
 A simple, flexible CMS engine for Ruby on Rails, designed for building highly interactive content with dynamic content blocks, declarative schemas, and ViewComponent widgets.
@@ -18,13 +21,16 @@ A simple, flexible CMS engine for Ruby on Rails, designed for building highly in
 
 ### 🛠️ Dedicated Admin Dashboard (`/cms`)
 - **Modern Zinc Aesthetic**: Clean, responsive monochrome layout with sticky sidebar navigation, top breadcrumbs, metric cards, quick-action buttons, and flash notification banners.
-- **Article CRUD & Friendly URLs**: Manage articles (`Macron::Cms::Article`) out-of-the-box with dedicated create, edit, show, and delete interfaces. Automatic slug generation via `friendly_id` produces clean SEO URLs.
+- **Article CRUD & Canonical Slugs**: Manage articles (`Macron::Cms::Article`) out-of-the-box with dedicated create, edit, show, and delete interfaces. Automatic slug generation via `friendly_id` produces clean SEO URLs.
+- **Publication Scheduling & Custom Chronology**: Configure exact `published_at` timestamps with an integrated datetime picker. Articles default to descending publication order (`published_at: :desc, created_at: :desc`), enabling scheduled publishing and custom sorting.
+- **Slug History & Canonical 301 Redirects**: Automatic FriendlyId slug history tracking. Host controllers use the `Macron::Cms::SlugRedirectable` concern to automatically issue permanent 301 redirects when an article is accessed via a previous slug, maintaining SEO equity and preventing 404s.
 - **Deletion Safeguards**: Browser confirmation dialogs on delete actions with article titles to prevent accidental deletion.
 - **Host App Integration**: Quick links between the CMS admin console and public-facing host views.
 
 ### 🧱 Dynamic Article Content Blocks & In-Place Inserters
 - **Multiple Blocks Per Article**: Associate an arbitrary series of content blocks with an article (`Macron::Cms::ArticleContent`). Add multiple blocks of the same content type (e.g. headings, markdown blocks, images) with distinct values.
 - **In-Place Block Inserters**: Add new blocks directly above, between, or below existing blocks on the Article management screen with one click.
+- **Declarative In-Place Block Conversion**: Convert blocks between compatible content types directly in-place (e.g. `image` <-> `three_js_image`) via the `convertible_to` schema definition. Conversions update records in place without duplicating Active Storage file attachments, and preserve existing and dormant JSONB `payload` attributes non-destructively.
 - **Inline Turbo Stream Updates**: Add, edit, and reorder content blocks with instantaneous Turbo Stream updates—no full-page reloads.
 - **Dynamic Field Generation**: Field controls are generated dynamically based on the content type schema and validated before saving into the block's `payload` JSONB column.
 - **8 Extensible Field Kinds**:
@@ -38,6 +44,11 @@ A simple, flexible CMS engine for Ruby on Rails, designed for building highly in
   - `latex`: CodeMirror LaTeX editor with `stex` syntax mode and KaTeX mathematical equation preview.
 - **File Attachment Purging**: Remove or replace existing Active Storage attachments directly from the block editor with a dedicated purge checkbox, keeping payloads clean without recreating blocks.
 
+### 🖼️ Automatic Featured Image Bubbling
+- **Declarative Tagging**: Tag image-bearing content types with `featured_image: true` in their YAML schemas (`config/content_types/*.yml`).
+- **Write-Time Image Bubbling**: Active Storage image attachments on eligible blocks automatically bubble up to `article.featured_image_blob` upon saving or deleting blocks, pointing to the first attached image in block sort order.
+- **Zero-Join Editorial Streams**: Eager-load and render article feeds or homepage streams (`@articles = Macron::Cms::Article.includes(:featured_image_blob)`) and access `article.featured_image` without expensive multi-table joins across heterogeneous content blocks.
+
 ### 🎨 Article Background & Typography Customization
 - **Custom Background Colors & Images**: Configure an optional background color or attach a background image directly to any article via Active Storage, with live image previews and one-click purge.
 - **CSS Background Display Controls**: Fine-tune background display settings per article:
@@ -52,12 +63,15 @@ A simple, flexible CMS engine for Ruby on Rails, designed for building highly in
 - **CodeMirror Markdown & LaTeX Editors**: Integrated CodeMirror editors in the CMS admin for writing Markdown content and raw LaTeX expressions with syntax highlighting (`stex` mode).
 - **Fast KaTeX Math Rendering**: Embedded KaTeX engine renders complex LaTeX equations, mathematical notation, and symbols instantaneously in both admin previews and front-end layouts.
 - **Formatted Markdown Previews**: Formatted GitHub Flavored Markdown (GFM) previews rendered directly on the article management page.
-- **Sandboxed Embeds**: Render third-party media and raw HTML snippets safely inside isolated `<iframe>` elements using `srcdoc` to prevent Active Storage download blocks and script collisions.
+- **Sandboxed Embeds with Configurable Heights**: Render third-party media and raw HTML snippets safely inside isolated `<iframe>` elements using `srcdoc` to prevent Active Storage download blocks and script collisions. Configure display heights (`sm`: 240px, `md`: 320px, `lg`: 480px, `xl`: 640px, `2xl`: 800px) alongside responsive widths (`25%` to `100%`).
+- **Native Fullscreen Maximize**: Embed containers feature a floating toggle button powered by the HTML5 Fullscreen API (`widgets/embed.js`), allowing users to expand embedded presentations, charts, or maps to full screen.
 - **Responsive Media Controls**: Configure image and embed widgets with responsive width options (`25%`, `33%`, `50%`, `66%`, `75%`, `100%`) and alignment (`left`, `center`, `right`).
 
-### ↕️ Drag-and-Drop & Button Reordering
+### ↕️ Drag-and-Drop, Compact View & Batch Reordering
 - **HTML5 Drag-and-Drop**: Easily re-arrange article content blocks on the Article show page with immediate position updates and asynchronous persistence.
 - **Accessible Move Up / Down Buttons**: Keyboard- and mobile-friendly reordering buttons on each block card as a built-in fallback.
+- **High-Density Compact View**: Segmented toggle (`?view=compact`) for rapid content reordering across long articles. Compact mode hides in-between inserters, displays the primary field defined in the schema (`primary_field`), and clamps text output to two lines for streamlined scanning.
+- **Shift+Click Multi-Selection & Multi-Drag**: Select multiple blocks in compact view using checkboxes or Shift+Click contiguous range selection with an active selection count badge. Dragging any selected card moves the entire group contiguously to the drop target.
 
 ### 🧩 Declarative Content Types & Generators
 - **YAML-Defined Schemas**: Define structured content types with typed fields (`name:kind`) stored directly in source control (`config/content_types/*.yml`).
@@ -69,16 +83,27 @@ A simple, flexible CMS engine for Ruby on Rails, designed for building highly in
 - **Seamless Rendering Helpers**: Render all article content blocks ordered by `sort_order` with `<%= cms_render_article_contents(@article) %>`, or render individual blocks via `<%= cms_render_widget(article_content) %>`.
 - **Informative Error Handling**: Raises `Macron::Cms::MissingWidgetError` if a content type does not have a corresponding `Widgets::<Name>Component` in the host application.
 
+### ⚡ High-Performance Preloading & O(1) Queries
+- **Zero N+1 Query Overhead**: Built-in `ArticleContent.for_display` scope combines Active Storage's `with_attached_files` with `.includes(:content)` to preload associations in constant-time batches.
+- **Bounded Query Execution**: Admin show views, high-frequency Turbo Stream inserts/reorders, and public host rendering (`cms_render_article_contents`) run in bounded O(1) database queries regardless of article length or attached media count.
+
 ### 🔒 Devise Authentication & Authorization
 - **Configurable Access Guard**: Protect the `/cms` engine namespace behind host application authentication.
 - **Role Customization**: Configure custom user models (`user_class`) and admin flags (`admin_flag`) via initializers.
 
-### 🤖 REST API & AI Content Ingestion (`/cms/api/v1`)
-- **Atomic Nested Import**: Create or update articles and complete sequences of typed content blocks in a single atomic transaction.
-- **Automated Remote Asset Ingestion**: Remote image URLs (e.g. Substack, Medium, WordPress) are automatically downloaded, validated, and attached to Active Storage blobs.
-- **Idempotent Upsert Support**: Re-run imports safely using `upsert: true` without creating duplicate articles.
+### 🤖 Granular REST API & Headless Operations (`/cms/api/v1`)
+- **Granular Block-Level Operations**: Full REST control over article blocks under `/cms/api/v1/articles/:article_id/content_blocks`—create with relative positioning (`insert_at`), update payloads, move blocks (`PATCH :id/move`), convert types in place (`PATCH :id/convert`), delete blocks, and batch reorder (`PATCH reorder`).
+- **Inline & Remote Asset Ingestion**: Attach files directly using base64 data payloads (`file_upload`) or provide remote URLs (`image_url` / `upload_url`) with automatic MIME detection and background Active Storage attachment.
+- **Atomic Nested Import & Upsert**: Create or update articles and complete sequences of typed content blocks in a single atomic transaction with `upsert: true`.
+- **Article Lifecycle Control**: Programmatically manage article metadata, publishing timestamps (`published_at`), and deletion via `PATCH` and `DELETE /cms/api/v1/articles/:id`.
+- **Historical Slug Resolution**: Requests referencing previous slugs resolve with `200 OK` and return the current canonical slug in the response, preventing integration breaks.
 - **Content Type Schema Introspection**: Query `GET /cms/api/v1/content_types` dynamically so AI agents know exact fields and widget types available.
 - **Bearer Token Auth**: Secure endpoints with `Authorization: Bearer <token>` or `X-API-Key`.
+- **Full API Documentation**: Complete endpoint specifications, payload schemas, and response models in [`docs/api.md`](docs/api.md).
+
+### 🧠 Model Context Protocol (MCP) Server
+- **Turnkey AI Pair-Programming**: Connect Claude Desktop, Cursor, Antigravity, or autonomous agents to MacronCMS via the official [macron-cms-mcp](https://github.com/macron1-automations/macron-cms-mcp) server.
+- **Native AI Tool Calling**: Enables LLMs to dynamically inspect schemas, draft articles, insert/edit blocks, reorder sections, and upload media assets natively using structured tool definitions.
 
 ### 🎨 Self-Contained Tailwind CSS v4
 - **Zero Host Setup Required**: MacronCMS packages its own standalone, precompiled Tailwind CSS v4 bundle (`app/assets/stylesheets/macron/cms/application.css`). Host applications do not need Tailwind installed to display the CMS admin interface.
@@ -165,7 +190,7 @@ This generates:
 
 ---
 
-### 2. Supported Field Kinds
+### 2. Supported Field Kinds & Schema Options
 
 | Kind | Description | Config Options | Accessor in Widget |
 |---|---|---|---|
@@ -178,6 +203,18 @@ This generates:
 | `json` | Formatted JSON editor | — | `field_name` |
 | `latex` | Mathematical formula editor with CodeMirror & KaTeX | — | `field_name` |
 
+#### Schema Configuration Options
+
+In addition to fields, content type schemas support top-level configuration options:
+
+| Option | Type | Description |
+|---|---|---|
+| `name` | String | Human-readable name of the content type |
+| `description` | String | Detailed description displayed in the CMS admin dashboard |
+| `featured_image` | Boolean | Set to `true` to declare this block as an image source for article featured image bubbling |
+| `convertible_to` | Array of strings | Target content types eligible for declarative in-place conversion |
+| `primary_field` | String | Designation of the field displayed as the primary preview in compact block view |
+
 ---
 
 ### 3. Schema Examples
@@ -215,6 +252,9 @@ fields:
 ```yaml
 name: Image
 description: Image with configurable responsive width, alignment, and optional caption
+featured_image: true
+convertible_to:
+  - three_js_image
 fields:
   - name: file
     kind: file
@@ -253,6 +293,19 @@ fields:
       - 66%
       - 75%
       - 100%
+  - name: height
+    kind: dropdown
+    options:
+      - name: Small (240px)
+        value: sm
+      - name: Medium (320px)
+        value: md
+      - name: Large (480px)
+        value: lg
+      - name: Extra Large (640px)
+        value: xl
+      - name: Very Large (800px)
+        value: 2xl
   - name: align
     kind: dropdown
     options:
@@ -346,6 +399,72 @@ fields:
         value: strong
 ```
 
+#### Interactive 3D Image Effects (`config/content_types/three_js_image.yml`)
+```yaml
+featured_image: true
+convertible_to:
+  - image
+fields:
+  - name: upload
+    kind: file
+  - name: size
+    kind: dropdown
+    options:
+      - name: Small (33%)
+        value: sm
+      - name: Medium (50%)
+        value: md
+      - name: Large (75%)
+        value: lg
+      - name: Full Width (100%)
+        value: full
+  - name: effect
+    kind: dropdown
+    options:
+      - name: Water Ripple
+        value: ripple
+      - name: Underwater Wave
+        value: wave
+      - name: RGB Glitch
+        value: glitch
+  - name: animation_speed
+    kind: dropdown
+    options:
+      - name: Slow
+        value: slow
+      - name: Normal
+        value: normal
+      - name: Fast
+        value: fast
+  - name: intensity
+    kind: dropdown
+    options:
+      - name: Subtle
+        value: subtle
+      - name: Medium
+        value: medium
+      - name: Strong
+        value: strong
+  - name: canvas_height
+    kind: dropdown
+    options:
+      - name: Small (240px)
+        value: sm
+      - name: Medium (320px)
+        value: md
+      - name: Large (480px)
+        value: lg
+      - name: Extra Large (640px)
+        value: xl
+  - name: fit_mode
+    kind: dropdown
+    options:
+      - name: Cover (Fill & Crop)
+        value: cover
+      - name: Contain (Fit Inside)
+        value: contain
+```
+
 ---
 
 ### 4. Importing Content Types
@@ -368,6 +487,54 @@ The import task is idempotent and creates or updates existing records. Once impo
 
 ### 5. Front-End Integration & ViewComponent Widgets
 
+#### Host Application Controller (`app/controllers/articles_controller.rb`)
+
+Include `Macron::Cms::SlugRedirectable` in your host controller to automatically issue canonical 301 permanent redirects if a visitor or search engine arrives via an outdated historical slug:
+
+```ruby
+class ArticlesController < ApplicationController
+  include Macron::Cms::SlugRedirectable
+
+  def show
+    @article = Macron::Cms::Article.friendly.find(params[:id])
+    redirect_to_canonical_slug_if_needed(@article)
+  end
+end
+```
+
+#### Editorial Stream & Featured Images (`app/views/pages/index.html.erb`)
+
+When listing articles on a homepage or editorial index, eager-load `:featured_image_blob` to display automatically bubbled featured images with zero N+1 database queries:
+
+```ruby
+# app/controllers/pages_controller.rb
+class PagesController < ApplicationController
+  def index
+    # Default scope orders chronologically by published_at DESC, created_at DESC
+    @articles = Macron::Cms::Article.includes(:featured_image_blob)
+  end
+end
+```
+
+```erb
+<%# app/views/pages/index.html.erb %>
+<div class="space-y-6">
+  <% @articles.each do |article| %>
+    <div class="flex items-start gap-4">
+      <% if article.featured_image.present? %>
+        <%= link_to article_path(article), class: "shrink-0" do %>
+          <%= image_tag article.featured_image, class: "w-24 h-24 object-cover rounded-lg border border-zinc-200" %>
+        <% end %>
+      <% end %>
+      <div>
+        <h2 class="text-xl font-bold"><%= link_to article.title, article_path(article) %></h2>
+        <p class="text-sm text-zinc-600 line-clamp-2"><%= article.seo_description %></p>
+      </div>
+    </div>
+  <% end %>
+</div>
+```
+
 #### Host Application View (`app/views/articles/show.html.erb`)
 
 Use `cms_seo_meta` for SEO metadata and `cms_article_background_style` to apply custom background colors, images, and text colors directly to the layout:
@@ -411,6 +578,8 @@ In your application layout (`app/views/layouts/application.html.erb`), apply the
   <%= javascript_include_tag "vendor/three_text_bundle", "data-turbo-track": "reload", defer: true %>
   <%= javascript_include_tag "vendor/three_fonts_bundle", "data-turbo-track": "reload", defer: true %>
   <%= javascript_include_tag "widgets/three_js_quote", "data-turbo-track": "reload", defer: true %>
+  <%= javascript_include_tag "widgets/three_js_image", "data-turbo-track": "reload", defer: true %>
+  <%= javascript_include_tag "widgets/embed", "data-turbo-track": "reload", defer: true %>
 </head>
 
 <body class="min-h-screen text-zinc-900 <%= 'bg-zinc-50' unless content_for?(:body_style) %>"
@@ -522,8 +691,17 @@ end
 # app/components/widgets/embed_component.rb
 module Widgets
   class EmbedComponent < Macron::Cms::WidgetComponent
+    HEIGHT_CLASSES = {
+      "sm"  => "h-60 sm:h-72",
+      "md"  => "h-72 sm:h-80",
+      "lg"  => "h-96 sm:h-[480px]",
+      "xl"  => "h-[540px] sm:h-[640px]",
+      "2xl" => "h-[640px] sm:h-[800px]"
+    }.freeze
+    DEFAULT_HEIGHT = "lg"
+
     def embed_html
-      field_value(:html).to_s
+      field_value(:html).presence || (upload.present? ? upload.download.force_encoding("UTF-8") : nil)
     end
 
     def width_class
@@ -544,18 +722,42 @@ module Widgets
       else "mx-auto"
       end
     end
+
+    def height_class
+      h = field_value(:height).to_s.strip.downcase
+      HEIGHT_CLASSES[h] || HEIGHT_CLASSES[DEFAULT_HEIGHT]
+    end
   end
 end
 ```
 
 ```erb
 <%# app/components/widgets/embed_component.html.erb %>
-<div class="<%= width_class %> <%= align_class %> my-6">
+<div class="relative group my-6 <%= width_class %> <%= align_class %> overflow-hidden rounded-xl border border-zinc-200 bg-white shadow-xs [&:fullscreen]:m-0 [&:fullscreen]:w-screen [&:fullscreen]:h-screen [&:fullscreen]:rounded-none" data-embed-card>
+  <!-- Fullscreen Toggle Button -->
+  <button
+    type="button"
+    class="absolute top-3 right-3 z-10 flex h-8 w-8 items-center justify-center rounded-lg bg-zinc-900/60 text-white backdrop-blur-xs transition hover:bg-zinc-900/90 focus:outline-none opacity-70 group-hover:opacity-100 cursor-pointer"
+    data-embed-fullscreen-btn
+    aria-label="Maximize"
+    title="Maximize"
+  >
+    <svg class="h-4 w-4" data-icon-enter-fullscreen fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M3.75 3.75v4.5m0-4.5h4.5m-4.5 0L9 9M3.75 20.25v-4.5m0 4.5h4.5m-4.5 0L9 15M20.25 3.75h-4.5m4.5 0v4.5m0-4.5L15 9m5.25 11.25h-4.5m4.5 0v-4.5m0 4.5L15 15" />
+    </svg>
+    <svg class="h-4 w-4 hidden" data-icon-exit-fullscreen fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M9 9V4.5M9 9H4.5M9 9 3.75 3.75M9 15v4.5M9 15H4.5M9 15l-5.25 5.25M15 9h4.5M15 9V4.5M15 9l5.25-5.25M15 15h4.5M15 15v4.5m0-4.5 5.25 5.25" />
+    </svg>
+  </button>
+
   <iframe
     srcdoc="<%= embed_html %>"
+    class="w-full <%= height_class %> border-0 [&.is-fullscreen-iframe]:h-full"
     sandbox="allow-scripts allow-same-origin allow-popups allow-forms"
-    class="w-full border-0 rounded overflow-hidden"
-    loading="lazy">
+    allowfullscreen
+    allow="fullscreen"
+    loading="lazy"
+    title="Embedded content">
   </iframe>
 </div>
 ```
@@ -704,6 +906,9 @@ end
 
 MacronCMS provides a JSON REST API under `/cms/api/v1/` designed for programmatic ingestion, automated scripts, and autonomous AI agents migrating content from external platforms (such as Substack, WordPress, or Medium).
 
+> [!TIP]
+> For the complete endpoint reference, request/response payload schemas, parameter definitions, and status codes, see the dedicated [**REST API Documentation (`docs/api.md`)**](docs/api.md). If you are building an automated ingestion pipeline or AI migration agent, refer to the [**AI Article Importer Guide (`docs/ai_importer_guide.md`)**](docs/ai_importer_guide.md).
+
 ### Authentication
 
 API endpoints are secured using a Bearer token or API key header:
@@ -724,16 +929,24 @@ Configure your key in an initializer (`config.api_key`) or via the `MACRON_CMS_A
 
 | Method | Endpoint | Description |
 |---|---|---|
-| `POST` | `/cms/api/v1/articles` | Create or upsert an article with nested content blocks |
-| `GET` | `/cms/api/v1/articles/:id` | Retrieve article metadata and ordered content blocks (JSON) |
-| `PATCH` | `/cms/api/v1/articles/:id` | Update article attributes and synchronize content blocks |
-| `GET` | `/cms/api/v1/content_types` | Introspect available content types and schema field requirements |
+| `GET` | [`/cms/api/v1/content_types`](docs/api.md#1-list-content-types-get-cmsapiv1content_types) | Introspect available content types and schema field requirements |
+| `GET` | [`/cms/api/v1/articles`](docs/api.md#2-list-articles-get-cmsapiv1articles) | List articles with metadata, slugs, and publication dates |
+| `POST` | [`/cms/api/v1/articles`](docs/api.md#3-create-or-upsert-article-post-cmsapiv1articles) | Create or upsert an article with nested content blocks |
+| `GET` | [`/cms/api/v1/articles/:id`](docs/api.md#4-retrieve-article-get-cmsapiv1articlesid) | Retrieve article metadata and ordered content blocks (JSON) |
+| `PATCH` | [`/cms/api/v1/articles/:id`](docs/api.md#5-update-article-patch-cmsapiv1articlesid) | Update article metadata and synchronize content blocks |
+| `DELETE` | [`/cms/api/v1/articles/:id`](docs/api.md#6-delete-article-delete-cmsapiv1articlesid) | Delete an article and its associated content blocks |
+| `POST` | [`/cms/api/v1/articles/:article_id/content_blocks`](docs/api.md#7-content-block-operations) | Insert a content block (supports `insert_at` and `file_upload`) |
+| `PATCH` | [`/cms/api/v1/articles/:article_id/content_blocks/:id`](docs/api.md#7-content-block-operations) | Update payload attributes, replace files, or purge attachments |
+| `DELETE` | [`/cms/api/v1/articles/:article_id/content_blocks/:id`](docs/api.md#7-content-block-operations) | Delete a content block and re-normalize sequence order |
+| `PATCH` | [`/cms/api/v1/articles/:article_id/content_blocks/:id/move`](docs/api.md#7-content-block-operations) | Move block position (`up`, `down`, or target position) |
+| `PATCH` | [`/cms/api/v1/articles/:article_id/content_blocks/:id/convert`](docs/api.md#7-content-block-operations) | Convert block in-place to compatible schema type |
+| `PATCH` | [`/cms/api/v1/articles/:article_id/content_blocks/reorder`](docs/api.md#7-content-block-operations) | Batch reorder blocks via array of ordered IDs |
 
 ---
 
 ### 1. Ingesting Articles with Nested Content Blocks
 
-You can import an entire article—including its metadata, SEO tags, colors, and an ordered list of typed content blocks—in a single atomic transaction:
+You can import an entire article—including its metadata, SEO tags, colors, publication timestamp (`published_at`), and an ordered list of typed content blocks—in a single atomic transaction:
 
 ```bash
 curl -X POST http://localhost:3000/cms/api/v1/articles \
@@ -743,7 +956,8 @@ curl -X POST http://localhost:3000/cms/api/v1/articles \
     "upsert": true,
     "article": {
       "title": "The Myth of Your Limitations",
-      "name": "the-myth-of-your-limitations",
+      "slug": "the-myth-of-your-limitations",
+      "published_at": "2026-10-29T19:30:00Z",
       "meta_title": "The Myth of Your Limitations | Mindset Guide",
       "meta_description": "How a simple mindset shift can prove you wrong.",
       "background_color": "#ffffff",
@@ -776,7 +990,7 @@ curl -X POST http://localhost:3000/cms/api/v1/articles \
 When an `image_url` (or `upload_url`) is provided in a content block, MacronCMS automatically downloads the asset from the remote source (e.g. Substack CDN), verifies content size and type, and attaches it as an Active Storage blob on the content block. If the remote server is unreachable, it gracefully falls back to storing the direct URL in the block payload.
 
 #### Idempotent Upserting
-When `"upsert": true` is specified, the API searches for an existing article matching `name`, `slug`, or `title`. If found, it updates the article attributes and atomically replaces its content blocks with the incoming sequence, making bulk migrations safe to re-run.
+When `"upsert": true` is specified, the API searches for an existing article matching `slug` or `title`. If found, it updates the article attributes and atomically replaces its content blocks with the incoming sequence, making bulk migrations safe to re-run.
 
 ---
 
@@ -794,20 +1008,119 @@ AI agents can query `/cms/api/v1/content_types` before generating payloads to dy
         { "name": "title", "kind": "string" },
         { "name": "level", "kind": "dropdown", "options": ["h1", "h2", "h3", "h4", "h5", "h6"] },
         { "name": "color", "kind": "color" }
-      ]
+      ],
+      "convertible_to": [],
+      "featured_image": false
     },
     {
       "id": 2,
-      "name": "markdown",
+      "name": "image",
       "fields": [
-        { "name": "content", "kind": "markdown" }
-      ]
+        { "name": "upload", "kind": "file" },
+        { "name": "size", "kind": "dropdown", "options": ["sm", "md", "lg", "full"] }
+      ],
+      "convertible_to": [
+        "three_js_image"
+      ],
+      "featured_image": true
     }
   ]
 }
 ```
 
-For complete mapping rules from Substack HTML tags and a ready-to-use prompt template for AI agents, see [`docs/ai_importer_guide.md`](docs/ai_importer_guide.md).
+---
+
+### 3. Granular Content Block Operations
+
+MacronCMS supports fine-grained REST manipulation of article blocks, allowing agents and scripts to make targeted edits without replacing the entire article:
+
+#### Add Block with Inline Base64 Asset
+```bash
+curl -X POST http://localhost:3000/cms/api/v1/articles/the-myth-of-your-limitations/content_blocks \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer test-secret-key" \
+  -d '{
+    "content_type": "image",
+    "insert_at": 2,
+    "payload": { "size": "md" },
+    "file_upload": {
+      "filename": "diagram.png",
+      "content_type": "image/png",
+      "data_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
+    }
+  }'
+```
+
+#### In-Place Block Conversion
+```bash
+curl -X PATCH http://localhost:3000/cms/api/v1/articles/the-myth-of-your-limitations/content_blocks/42/convert \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer test-secret-key" \
+  -d '{ "target_content_type": "three_js_image" }'
+```
+
+#### Reordering and Relative Moves
+```bash
+# Shift block up or down relative to its current position
+curl -X PATCH http://localhost:3000/cms/api/v1/articles/the-myth-of-your-limitations/content_blocks/42/move \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer test-secret-key" \
+  -d '{ "direction": "up" }'
+
+# Or batch reorder by an explicit list of block IDs
+curl -X PATCH http://localhost:3000/cms/api/v1/articles/the-myth-of-your-limitations/content_blocks/reorder \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer test-secret-key" \
+  -d '{ "ordered_ids": [45, 42, 43, 44] }'
+```
+
+For complete endpoint specifications, payload schemas, and response formats, see [`docs/api.md`](docs/api.md). For Substack HTML mapping rules and a ready-to-use prompt template for AI agents, see [`docs/ai_importer_guide.md`](docs/ai_importer_guide.md).
+
+---
+
+## 🤖 Model Context Protocol (MCP) Server
+
+MacronCMS includes an official **Model Context Protocol (MCP) Server**: [**`macron-cms-mcp`**](https://github.com/macron1-automations/macron-cms-mcp).
+
+The MCP server connects AI coding assistants and autonomous agents—including Claude Desktop, Cursor, and Antigravity—directly to MacronCMS, exposing rich tool-calling capabilities to manage and pair-program content directly from within your agent workflow.
+
+### Available MCP Tools
+
+| Tool | Description |
+|---|---|
+| `list_content_types` | Introspect all registered YAML content types, field specifications, and type converters |
+| `list_articles` | Retrieve articles with metadata, canonical slugs, and publication timestamps |
+| `get_article` | Fetch article details and its ordered content blocks |
+| `create_article` | Scaffold a new article with optional nested blocks and publication scheduling |
+| `update_article_metadata` | Update article title, slug, publication date, text/background styling, or SEO tags |
+| `delete_article` | Delete an article and its content blocks |
+| `add_content_block` | Insert a new content block at a specific position with payload or Base64 attachments |
+| `update_content_block` | Modify block payload attributes, replace attachments, or purge files |
+| `delete_content_block` | Remove a block and automatically re-normalize sequence ordering |
+| `move_content_block` | Shift block position up, down, or to an explicit target index |
+| `reorder_content_blocks` | Batch reorder all blocks on an article |
+| `convert_content_block` | In-place convert a block between compatible content types (e.g. `image` ↔ `three_js_image`) |
+
+### AI Agent / Client Configuration
+
+Add the server to your MCP client configuration (such as `claude_desktop_config.json` or your Antigravity / Cursor MCP configuration):
+
+```json
+{
+  "mcpServers": {
+    "macron-cms": {
+      "command": "npx",
+      "args": ["-y", "@macron1/cms-mcp"],
+      "env": {
+        "MACRON_CMS_BASE_URL": "http://localhost:3000/cms/api/v1",
+        "MACRON_CMS_API_KEY": "<your-api-key>"
+      }
+    }
+  }
+}
+```
+
+For full installation and tool usage documentation, visit the [**macron-cms-mcp repository on GitHub**](https://github.com/macron1-automations/macron-cms-mcp).
 
 ---