domma-cms 1.6.60 → 1.7.0

package/docs/plans/2026-03-09-pro-documentation.md

@@ -0,0 +1,1017 @@
+# Pro Documentation Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a Pro documentation section - four public `/resources/pro/` pages (index, Views, Actions, CTA shortcode) plus a single tabbed "Pro Documentation" admin panel under `#/pro/docs`.
+
+**Architecture:** Public pages are Markdown files following the existing resources pattern (hero + content + back link). The admin panel is a static HTML template with three tabs wired by a minimal JS view - mirrors the `documentationView` pattern exactly (templateUrl + onMount with icons + syntax scan).
+
+**Tech Stack:** Markdown pages (Domma shortcodes), Domma admin SPA (templateUrl views, E.tabs, Domma.syntax.scan), sidebar-config.js, views/index.js, app.js routes.
+
+---
+
+## Task 1: Public - Pro section index page
+
+**Files:**
+- Create: `content/pages/resources/pro/index.md`
+
+**Step 1: Create the Pro landing page**
+
+```markdown
+---
+title: Pro Features
+slug: pro
+description: >-
+  Pro features for Domma CMS - Views, Actions, and CTA shortcodes.
+  Requires MongoDB.
+layout: default
+status: published
+sortOrder: 20
+showInNav: false
+sidebar: false
+seo:
+  title: Pro Features - Resources
+  description: Domma CMS Pro features reference
+createdAt: '2026-03-09T00:00:00.000Z'
+updatedAt: '2026-03-09T00:00:00.000Z'
+tags: []
+category: null
+visibility: public
+dconfig: null
+---
+
+[hero variant="dark" size="sm" fullwidth="true" twinkle twinkle-count="20" blobs]
+
+# Pro Features
+
+Advanced features for Domma CMS requiring a MongoDB connection.
+
+[/hero]
+
+[badge style="warning"]Pro - requires MongoDB[/badge]
+
+Pro features use MongoDB as a storage backend. A named connection must be configured in `config/connections.json` before creating Views or Actions.
+
+[grid cols="3" gap="4"]
+[col]
+[card title="Views"]
+MongoDB aggregation pipelines exposed as named, role-gated endpoints. Filter, join, sort, and reshape your collection data.
+
+[Read more →](/resources/pro/views)
+[/card]
+[/col]
+[col]
+[card title="Actions"]
+Multi-step operations on collection entries - update fields, send webhooks, fire emails, move or delete entries - triggered manually or via the `[cta]` shortcode.
+
+[Read more →](/resources/pro/actions)
+[/card]
+[/col]
+[col]
+[card title="CTA Shortcode"]
+Place action-trigger buttons anywhere in your Markdown content. Works standalone or integrated with the `[collection]` shortcode for per-entry buttons.
+
+[Read more →](/resources/pro/cta)
+[/card]
+[/col]
+[/grid]
+
+← [Back to Resources](/resources)
+```
+
+**Step 2: Verify the page renders**
+
+```bash
+curl -s http://localhost:4096/resources/pro | grep -c "Pro Features"
+```
+Expected: `1` (or more)
+
+**Step 3: Commit**
+
+```bash
+git add content/pages/resources/pro/index.md
+git commit -m "feat: add /resources/pro landing page"
+```
+
+---
+
+## Task 2: Public - Views reference page
+
+**Files:**
+- Create: `content/pages/resources/pro/views.md`
+
+**Step 1: Create the Views page**
+
+```markdown
+---
+title: Views
+slug: views
+description: >-
+  MongoDB aggregation pipeline Views - filter, join, and reshape collection
+  data with role-gated public endpoints.
+layout: default
+status: published
+sortOrder: 21
+showInNav: false
+sidebar: false
+seo:
+  title: Views - Pro Features
+  description: Domma CMS Views reference
+createdAt: '2026-03-09T00:00:00.000Z'
+updatedAt: '2026-03-09T00:00:00.000Z'
+tags: []
+category: null
+visibility: public
+dconfig: null
+---
+
+[hero variant="dark" size="sm" fullwidth="true" twinkle twinkle-count="20" blobs]
+
+# Views
+
+[/hero]
+
+[badge style="warning"]Pro - requires MongoDB[/badge]
+
+A **View** is a saved MongoDB aggregation pipeline that runs against a collection and returns shaped results. Views are defined in the admin under **Data → Views** and exposed via a REST endpoint that respects role-level access and optional row-level filtering.
+
+---
+
+## Creating a View
+
+Go to **Data → Views → New View** and fill in:
+
+| Field | Description |
+|-------|-------------|
+| **Title** | Human-readable name shown in the admin |
+| **Slug** | URL-safe identifier - auto-generated from the title |
+| **Description** | Optional notes about what this View returns |
+| **Source Collection** | The primary collection the pipeline runs against |
+| **Connection** | MongoDB connection name from `config/connections.json` (default: `default`) |
+
+---
+
+## Pipeline Stages
+
+Switch to the **Pipeline** tab to add aggregation stages. Each stage is a JSON object using standard MongoDB aggregation syntax.
+
+### Allowed stages
+
+| Stage | Purpose |
+|-------|---------|
+| `$match` | Filter documents by field values |
+| `$sort` | Order results by one or more fields |
+| `$project` | Include, exclude, or rename fields |
+| `$lookup` | Join data from another collection |
+| `$unwind` | Flatten an array field into separate documents |
+| `$addFields` | Compute and add new fields |
+| `$group` | Aggregate documents (count, sum, etc.) |
+| `$limit` | Cap the number of results |
+| `$skip` | Skip N results (useful for manual pagination) |
+| `$count` | Return a document count |
+
+Stages `$out`, `$merge`, `$function`, `$accumulator`, and `$graphLookup` are **blocked** for security.
+
+### Collection naming
+
+The pipeline always runs on the MongoDB collection `cms_{slug}` - e.g. the `feedback` collection is stored as `cms_feedback`. Use this prefix when writing `$lookup` joins.
+
+### Example pipeline - active users with submission count
+
+```json
+[
+  { "$match": { "data.isActive": true } },
+  {
+    "$lookup": {
+      "from": "cms_feedback",
+      "localField": "_id",
+      "foreignField": "data.userId",
+      "as": "submissions"
+    }
+  },
+  {
+    "$addFields": {
+      "submissionCount": { "$size": "$submissions" }
+    }
+  },
+  { "$project": { "data.name": 1, "data.email": 1, "submissionCount": 1 } },
+  { "$sort": { "submissionCount": -1 } }
+]
+```
+
+---
+
+## Display Settings
+
+The **Display** tab controls how results appear in the admin preview and public endpoint:
+
+| Field | Description |
+|-------|-------------|
+| **Display Mode** | `table` (default) or `list` |
+| **Page Size** | Rows per page in the table (default 25) |
+| **Column Definitions** | JSON array: `[{"key":"data.name","label":"Name"}]` - `key` is dot-notation path into each result document |
+
+---
+
+## Access Control
+
+The **Access** tab controls who can call this View:
+
+- **Allowed Roles** - tick which roles can call `GET /api/views/:slug/public`
+- **Public** - when checked, no authentication is required at all
+- **Row-Level Access** - when enabled, each user only sees entries they own or are assigned to (admins always see everything)
+
+### Row-level modes
+
+| Mode | Behaviour |
+|------|-----------|
+| **Owner** | Only entries whose `meta.createdBy` matches the current user |
+| **Field Match** | A specified field on the entry must match a property of the current user (e.g. `assigned_to` = `user.id`) |
+
+---
+
+## Endpoints
+
+| Method | URL | Auth |
+|--------|-----|------|
+| `GET` | `/api/views` | Admin / manager |
+| `POST` | `/api/views` | Admin / manager |
+| `GET` | `/api/views/:slug` | Admin / manager |
+| `PUT` | `/api/views/:slug` | Admin / manager |
+| `DELETE` | `/api/views/:slug` | Admin / manager |
+| `GET` | `/api/views/:slug/execute` | Admin (preview) |
+| `GET` | `/api/views/:slug/public` | Role-gated (see Access tab) |
+
+---
+
+← [Back to Pro Features](/resources/pro)
+```
+
+**Step 2: Verify**
+
+```bash
+curl -s http://localhost:4096/resources/pro/views | grep -c "aggregation"
+```
+Expected: `1` (or more)
+
+**Step 3: Commit**
+
+```bash
+git add content/pages/resources/pro/views.md
+git commit -m "feat: add /resources/pro/views reference page"
+```
+
+---
+
+## Task 3: Public - Actions reference page
+
+**Files:**
+- Create: `content/pages/resources/pro/actions.md`
+
+**Step 1: Create the Actions page**
+
+```markdown
+---
+title: Actions
+slug: actions
+description: >-
+  Multi-step Actions on collection entries - update fields, send webhooks,
+  fire emails, and more.
+layout: default
+status: published
+sortOrder: 22
+showInNav: false
+sidebar: false
+seo:
+  title: Actions - Pro Features
+  description: Domma CMS Actions reference
+createdAt: '2026-03-09T00:00:00.000Z'
+updatedAt: '2026-03-09T00:00:00.000Z'
+tags: []
+category: null
+visibility: public
+dconfig: null
+---
+
+[hero variant="dark" size="sm" fullwidth="true" twinkle twinkle-count="20" blobs]
+
+# Actions
+
+[/hero]
+
+[badge style="warning"]Pro - requires MongoDB[/badge]
+
+An **Action** is a named sequence of steps that runs against a single collection entry. Actions are defined in the admin under **Data → Actions** and can be triggered manually from the entry list, or from any public page via the `[cta]` shortcode.
+
+---
+
+## Creating an Action
+
+Go to **Data → Actions → New Action** and fill in:
+
+| Field | Description |
+|-------|-------------|
+| **Title** | Human-readable name (e.g. *Approve Application*) |
+| **Slug** | URL-safe identifier - auto-generated from the title |
+| **Description** | Optional notes |
+| **Target Collection** | The collection this action operates on |
+
+---
+
+## Trigger Settings
+
+The **Trigger** tab controls how the Action is invoked from the admin:
+
+| Field | Description |
+|-------|-------------|
+| **Trigger Type** | Currently: `Manual` (button in the entry list) |
+| **Button Label** | Label shown on the trigger button (default: `Run`) |
+| **Button Icon** | Domma icon name (e.g. `check-circle`, `zap`, `send`) |
+| **Confirmation Message** | Optional prompt before execution - leave blank to skip |
+
+---
+
+## Steps
+
+The **Steps** tab defines what the Action does. Steps run in order. If a step fails, execution stops and a partial result is returned indicating how many steps completed.
+
+### Step types
+
+#### `updateField`
+
+Sets a field on the entry to a new value. Supports template variables.
+
+```json
+{
+  "field": "status",
+  "value": "approved"
+}
+```
+
+#### `deleteEntry`
+
+Permanently deletes the target entry. No additional config needed.
+
+#### `moveToCollection`
+
+Moves the entry to a different collection (copies data, then deletes from source).
+
+```json
+{
+  "targetCollection": "approved-applications"
+}
+```
+
+#### `webhook`
+
+POSTs the entry data to an external URL.
+
+```json
+{
+  "url": "https://hooks.example.com/notify",
+  "headers": { "X-Secret": "{{env.CMS_PUBLIC_HOOK_SECRET}}" }
+}
+```
+
+#### `email`
+
+Sends an email via the configured SMTP server (set in **Settings → Email / SMTP**).
+
+```json
+{
+  "to": "{{entry.data.email}}",
+  "subject": "Your application was approved",
+  "body": "Hi {{entry.data.name}},\n\nYour application has been approved."
+}
+```
+
+---
+
+## Template Variables
+
+All step field values support template interpolation using `{{...}}` syntax:
+
+| Variable | Value |
+|----------|-------|
+| `{{entry.data.fieldName}}` | Any field from the target entry |
+| `{{entry.id}}` | The entry's UUID |
+| `{{now}}` | Current timestamp in ISO 8601 format |
+| `{{user.name}}` | Name of the user who triggered the Action |
+| `{{user.email}}` | Email of the triggering user |
+| `{{user.id}}` | UUID of the triggering user |
+| `{{env.CMS_PUBLIC_*}}` | Public environment variables (prefixed `CMS_PUBLIC_`) |
+
+---
+
+## Access Control
+
+The **Access** tab works identically to Views:
+
+- **Allowed Roles** - who can call `POST /api/actions/:slug/public`
+- **Row-Level Access** - restrict execution to entries owned by or assigned to the current user
+
+---
+
+## Endpoints
+
+| Method | URL | Auth |
+|--------|-----|------|
+| `GET` | `/api/actions` | Admin / manager |
+| `POST` | `/api/actions` | Admin / manager |
+| `GET` | `/api/actions/:slug` | Admin / manager |
+| `PUT` | `/api/actions/:slug` | Admin / manager |
+| `DELETE` | `/api/actions/:slug` | Admin / manager |
+| `POST` | `/api/actions/:slug/execute` | Admin (test run) |
+| `POST` | `/api/actions/:slug/public` | Role-gated (see Access tab) |
+
+The public endpoint expects a JSON body: `{ "entryId": "uuid-of-entry" }`
+
+---
+
+← [Back to Pro Features](/resources/pro)
+```
+
+**Step 2: Verify**
+
+```bash
+curl -s http://localhost:4096/resources/pro/actions | grep -c "updateField"
+```
+Expected: `1` (or more)
+
+**Step 3: Commit**
+
+```bash
+git add content/pages/resources/pro/actions.md
+git commit -m "feat: add /resources/pro/actions reference page"
+```
+
+---
+
+## Task 4: Public - CTA shortcode reference page
+
+**Files:**
+- Create: `content/pages/resources/pro/cta.md`
+
+**Step 1: Create the CTA page**
+
+```markdown
+---
+title: CTA Shortcode
+slug: cta
+description: >-
+  Place Action-trigger buttons anywhere in your Markdown content using the
+  [cta] shortcode.
+layout: default
+status: published
+sortOrder: 23
+showInNav: false
+sidebar: false
+seo:
+  title: CTA Shortcode - Pro Features
+  description: Domma CMS CTA shortcode reference
+createdAt: '2026-03-09T00:00:00.000Z'
+updatedAt: '2026-03-09T00:00:00.000Z'
+tags: []
+category: null
+visibility: public
+dconfig: null
+---
+
+[hero variant="dark" size="sm" fullwidth="true" twinkle twinkle-count="20" blobs]
+
+# CTA Shortcode
+
+[/hero]
+
+The `[cta]` shortcode renders a button that triggers a named Action against a specific entry. The button uses the logged-in user's JWT to authenticate the request - no separate login is required if the user is already signed in to the admin.
+
+---
+
+## Syntax
+
+Two forms are supported:
+
+**Wrapping form** - button label comes from the body:
+
+```
+[cta action="slug" entry="entry-id"]Button label[/cta]
+```
+
+**Self-closing form** - button label from `label` attribute:
+
+```
+[cta action="slug" entry="entry-id" label="Button label" /]
+```
+
+---
+
+## Attributes
+
+| Attribute | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `action` | Yes | - | Slug of the Action to execute |
+| `entry` | Yes | - | UUID of the entry to act on |
+| `label` | No | `"Run"` | Button text (self-closing form only) |
+| `style` | No | `"primary"` | Button variant: `primary`, `secondary`, `ghost`, `danger` |
+| `icon` | No | - | Domma icon name shown before the label |
+| `size` | No | - | Button size: `sm`, `md`, `lg` |
+| `confirm` | No | - | Confirmation prompt text - shown before executing |
+
+---
+
+## Examples
+
+### Basic button
+
+```
+[cta action="approve-application" entry="abc-123"]Approve[/cta]
+```
+
+### With icon and confirmation
+
+```
+[cta action="approve-application" entry="abc-123" icon="check" style="primary" confirm="Approve this application?"]Approve[/cta]
+```
+
+### Danger button with confirmation
+
+```
+[cta action="delete-entry" entry="abc-123" style="danger" confirm="Permanently delete this entry?"]Delete[/cta]
+```
+
+### Self-closing form
+
+```
+[cta action="send-welcome-email" entry="abc-123" label="Send welcome email" icon="send" /]
+```
+
+---
+
+## Collection Integration
+
+Add per-entry CTA buttons to any `[collection]` shortcode by adding `cta` and related attributes:
+
+```
+[collection slug="applications" display="cards" title-field="name"
+  cta="approve-application"
+  cta-label="Approve"
+  cta-icon="check"
+  cta-style="primary"
+  cta-confirm="Approve this application?" /]
+```
+
+### Collection CTA attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `cta` | - | Action slug - enables per-entry buttons |
+| `cta-label` | `"Run"` | Button label |
+| `cta-icon` | - | Domma icon name |
+| `cta-style` | `"primary"` | Button variant |
+| `cta-confirm` | - | Confirmation prompt |
+
+All three display modes support CTA buttons: **cards** (footer), **list** (inline), and **table** (dedicated column).
+
+---
+
+## Authentication
+
+The button reads the user's token from `S.get('auth_token')` - the same token used by the admin panel. If the user is not logged in, clicking the button shows a warning toast:
+
+> *"Please log in to perform this action."*
+
+The Action's **Access** tab controls which roles are allowed to trigger it via the public endpoint.
+
+---
+
+← [Back to Pro Features](/resources/pro)
+```
+
+**Step 2: Verify**
+
+```bash
+curl -s http://localhost:4096/resources/pro/cta | grep -c "cta-label"
+```
+Expected: `1` (or more)
+
+**Step 3: Commit**
+
+```bash
+git add content/pages/resources/pro/cta.md
+git commit -m "feat: add /resources/pro/cta shortcode reference page"
+```
+
+---
+
+## Task 5: Update Resources index - add Pro card
+
+**Files:**
+- Modify: `content/pages/resources/index.md`
+
+**Step 1: Add a Pro Features card to the grid**
+
+In `content/pages/resources/index.md`, add a new `[col]` + `[card]` block inside the existing `[grid cols="3" gap="4"]` - after the last card (Dependencies) and before `[/grid]`:
+
+```
+[col]
+[card title="Pro Features"]
+Views, Actions, and the CTA shortcode - advanced features powered by MongoDB. [badge style="warning"]Pro[/badge]
+
+[Read more →](/resources/pro)
+[/card]
+[/col]
+```
+
+**Step 2: Verify the Resources index still renders**
+
+```bash
+curl -s http://localhost:4096/resources | grep -c "Pro Features"
+```
+Expected: `1`
+
+**Step 3: Commit**
+
+```bash
+git add content/pages/resources/index.md
+git commit -m "feat: add Pro Features card to resources index"
+```
+
+---
+
+## Task 6: Admin - Pro Documentation view JS + HTML template
+
+**Files:**
+- Create: `admin/js/views/pro-docs.js`
+- Create: `admin/js/templates/pro-docs.html`
+
+**Step 1: Create the view module**
+
+`admin/js/views/pro-docs.js`:
+
+```js
+/**
+ * Pro Documentation View
+ * Reference for Pro-only features: Views, Actions, and the CTA shortcode.
+ */
+export const proDocsView = {
+  templateUrl: '/admin/js/templates/pro-docs.html',
+
+  async onMount($container) {
+    E.tabs($container.find('#pro-docs-tabs').get(0));
+    Domma.icons.scan();
+    Domma.syntax.scan();
+  }
+};
+```
+
+**Step 2: Create the template**
+
+`admin/js/templates/pro-docs.html` - a three-tab layout (Views, Actions, CTA Shortcode). Each tab is a collapsible-card reference section matching the style of `documentation.html`.
+
+```html
+<div class="view-header">
+  <h1><span data-icon="zap"></span> Pro Documentation</h1>
+</div>
+
+<div class="tabs" id="pro-docs-tabs">
+  <div class="tab-list">
+    <button class="tab-item active">Views</button>
+    <button class="tab-item">Actions</button>
+    <button class="tab-item">CTA Shortcode</button>
+  </div>
+  <div class="tab-content">
+
+    <!-- ── Views tab ─────────────────────────────────────── -->
+    <div class="tab-panel active">
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="eye"></span> What is a View?</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <p>A <strong>View</strong> is a saved MongoDB aggregation pipeline that runs against a collection and returns shaped results. Views are created under <strong>Data → Views</strong> and exposed via a REST endpoint that respects role-level and row-level access.</p>
+          <p>Views require a MongoDB connection configured in <code>config/connections.json</code>.</p>
+        </div>
+      </div>
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="layers"></span> Allowed Pipeline Stages</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <table class="table table-sm">
+            <thead><tr><th>Stage</th><th>Purpose</th></tr></thead>
+            <tbody>
+              <tr><td><code>$match</code></td><td>Filter documents by field values</td></tr>
+              <tr><td><code>$sort</code></td><td>Order results</td></tr>
+              <tr><td><code>$project</code></td><td>Include, exclude, or rename fields</td></tr>
+              <tr><td><code>$lookup</code></td><td>Join from another collection</td></tr>
+              <tr><td><code>$unwind</code></td><td>Flatten an array field</td></tr>
+              <tr><td><code>$addFields</code></td><td>Compute new fields</td></tr>
+              <tr><td><code>$group</code></td><td>Aggregate (count, sum, etc.)</td></tr>
+              <tr><td><code>$limit</code></td><td>Cap results</td></tr>
+              <tr><td><code>$skip</code></td><td>Skip N results</td></tr>
+              <tr><td><code>$count</code></td><td>Return a document count</td></tr>
+            </tbody>
+          </table>
+          <p class="text-muted" style="margin-top:.75rem;">Blocked: <code>$out</code>, <code>$merge</code>, <code>$function</code>, <code>$accumulator</code>, <code>$graphLookup</code></p>
+          <p>Collections are prefixed <code>cms_</code> in MongoDB - use this prefix in <code>$lookup</code> <code>from</code> values.</p>
+        </div>
+      </div>
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="code"></span> Example Pipeline</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <p>Match active entries and count related submissions:</p>
+          <pre class="code-block"><code>[
+  { "$match": { "data.isActive": true } },
+  {
+    "$lookup": {
+      "from": "cms_feedback",
+      "localField": "_id",
+      "foreignField": "data.userId",
+      "as": "submissions"
+    }
+  },
+  { "$addFields": { "submissionCount": { "$size": "$submissions" } } },
+  { "$project": { "data.name": 1, "data.email": 1, "submissionCount": 1 } },
+  { "$sort": { "submissionCount": -1 } }
+]</code></pre>
+        </div>
+      </div>
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="lock"></span> Access Control</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <table class="table table-sm">
+            <thead><tr><th>Setting</th><th>Description</th></tr></thead>
+            <tbody>
+              <tr><td>Allowed Roles</td><td>Which roles can call <code>GET /api/views/:slug/public</code></td></tr>
+              <tr><td>Public</td><td>No authentication required when checked</td></tr>
+              <tr><td>Row-Level - Owner</td><td>User sees only entries they created</td></tr>
+              <tr><td>Row-Level - Field Match</td><td>A specified entry field must match a user property</td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+    </div><!-- /Views tab -->
+
+    <!-- ── Actions tab ───────────────────────────────────── -->
+    <div class="tab-panel">
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="zap"></span> What is an Action?</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <p>An <strong>Action</strong> is a named sequence of steps that runs against a single collection entry. Actions are defined under <strong>Data → Actions</strong> and can be triggered from the entry list or via the <code>[cta]</code> shortcode on any public page.</p>
+          <p>Actions require a MongoDB connection configured in <code>config/connections.json</code>.</p>
+          <p>Steps run in order. If a step fails, execution stops and a partial result is returned with a <code>stepsCompleted</code> count.</p>
+        </div>
+      </div>
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="list"></span> Step Types</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <table class="table table-sm">
+            <thead><tr><th>Type</th><th>What it does</th></tr></thead>
+            <tbody>
+              <tr><td><code>updateField</code></td><td>Sets a field on the entry to a new value</td></tr>
+              <tr><td><code>deleteEntry</code></td><td>Permanently deletes the target entry</td></tr>
+              <tr><td><code>moveToCollection</code></td><td>Moves the entry to a different collection</td></tr>
+              <tr><td><code>webhook</code></td><td>POSTs entry data to an external URL</td></tr>
+              <tr><td><code>email</code></td><td>Sends an email via the configured SMTP server</td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="tag"></span> Template Variables</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <p>All step field values support <code>&#123;&#123;...&#125;&#125;</code> interpolation:</p>
+          <table class="table table-sm">
+            <thead><tr><th>Variable</th><th>Value</th></tr></thead>
+            <tbody>
+              <tr><td><code>&#123;&#123;entry.data.fieldName&#125;&#125;</code></td><td>Any field from the target entry</td></tr>
+              <tr><td><code>&#123;&#123;entry.id&#125;&#125;</code></td><td>The entry's UUID</td></tr>
+              <tr><td><code>&#123;&#123;now&#125;&#125;</code></td><td>Current ISO 8601 timestamp</td></tr>
+              <tr><td><code>&#123;&#123;user.name&#125;&#125;</code></td><td>Name of the triggering user</td></tr>
+              <tr><td><code>&#123;&#123;user.email&#125;&#125;</code></td><td>Email of the triggering user</td></tr>
+              <tr><td><code>&#123;&#123;user.id&#125;&#125;</code></td><td>UUID of the triggering user</td></tr>
+              <tr><td><code>&#123;&#123;env.CMS_PUBLIC_*&#125;&#125;</code></td><td>Public environment variables</td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="code"></span> Step Examples</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <p><strong>updateField</strong> - mark an entry as approved:</p>
+          <pre class="code-block"><code>{ "field": "status", "value": "approved" }</code></pre>
+          <p><strong>webhook</strong> - notify an external service:</p>
+          <pre class="code-block"><code>{
+  "url": "https://hooks.example.com/notify",
+  "headers": { "X-Secret": "{{env.CMS_PUBLIC_HOOK_SECRET}}" }
+}</code></pre>
+          <p><strong>email</strong> - send confirmation to applicant:</p>
+          <pre class="code-block"><code>{
+  "to": "{{entry.data.email}}",
+  "subject": "Your application was approved",
+  "body": "Hi {{entry.data.name}}, your application has been approved."
+}</code></pre>
+        </div>
+      </div>
+
+    </div><!-- /Actions tab -->
+
+    <!-- ── CTA Shortcode tab ──────────────────────────────── -->
+    <div class="tab-panel">
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="mouse-pointer"></span> What is the CTA shortcode?</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <p>The <code>[cta]</code> shortcode places an action-trigger button in any public page. Clicking it calls <code>POST /api/actions/:slug/public</code> with the entry ID, using the logged-in user's JWT.</p>
+          <p>If the user is not logged in, a warning toast is shown instead.</p>
+        </div>
+      </div>
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="code"></span> Syntax &amp; Attributes</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <p><strong>Wrapping form:</strong></p>
+          <pre class="code-block"><code>[cta action="slug" entry="entry-id" icon="check" confirm="Are you sure?"]Button label[/cta]</code></pre>
+          <p><strong>Self-closing form:</strong></p>
+          <pre class="code-block"><code>[cta action="slug" entry="entry-id" label="Button label" /]</code></pre>
+          <table class="table table-sm" style="margin-top:1rem;">
+            <thead><tr><th>Attribute</th><th>Required</th><th>Default</th><th>Description</th></tr></thead>
+            <tbody>
+              <tr><td><code>action</code></td><td>Yes</td><td>-</td><td>Action slug</td></tr>
+              <tr><td><code>entry</code></td><td>Yes</td><td>-</td><td>Entry UUID to act on</td></tr>
+              <tr><td><code>label</code></td><td>No</td><td><code>"Run"</code></td><td>Button text (self-closing only)</td></tr>
+              <tr><td><code>style</code></td><td>No</td><td><code>"primary"</code></td><td>primary · secondary · ghost · danger</td></tr>
+              <tr><td><code>icon</code></td><td>No</td><td>-</td><td>Domma icon name</td></tr>
+              <tr><td><code>size</code></td><td>No</td><td>-</td><td>sm · md · lg</td></tr>
+              <tr><td><code>confirm</code></td><td>No</td><td>-</td><td>Confirmation prompt before executing</td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="grid"></span> Collection Integration</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <p>Add per-entry buttons to any <code>[collection]</code> shortcode:</p>
+          <pre class="code-block"><code>[collection slug="applications" display="cards" title-field="name"
+  cta="approve-application"
+  cta-label="Approve"
+  cta-icon="check"
+  cta-style="primary"
+  cta-confirm="Approve this application?" /]</code></pre>
+          <table class="table table-sm" style="margin-top:1rem;">
+            <thead><tr><th>Attribute</th><th>Default</th><th>Description</th></tr></thead>
+            <tbody>
+              <tr><td><code>cta</code></td><td>-</td><td>Action slug - enables per-entry buttons</td></tr>
+              <tr><td><code>cta-label</code></td><td><code>"Run"</code></td><td>Button label</td></tr>
+              <tr><td><code>cta-icon</code></td><td>-</td><td>Domma icon name</td></tr>
+              <tr><td><code>cta-style</code></td><td><code>"primary"</code></td><td>Button variant</td></tr>
+              <tr><td><code>cta-confirm</code></td><td>-</td><td>Confirmation prompt</td></tr>
+            </tbody>
+          </table>
+          <p>All three display modes support CTA buttons: <strong>cards</strong> (card footer), <strong>list</strong> (inline), <strong>table</strong> (dedicated column).</p>
+        </div>
+      </div>
+
+      <div class="card card-collapsible mb-4">
+        <div class="card-header" role="button" tabindex="0">
+          <div class="card-header-content"><h2><span data-icon="book-open"></span> Full Reference</h2></div>
+          <span class="card-collapse-icon" data-icon="chevron-down"></span>
+        </div>
+        <div class="card-body docs-body">
+          <p>See the public documentation for live examples and the complete attribute reference:</p>
+          <a href="/resources/pro/cta" target="_blank" class="btn btn-ghost btn-sm">
+            <span data-icon="external-link"></span> CTA Shortcode Reference
+          </a>
+        </div>
+      </div>
+
+    </div><!-- /CTA tab -->
+
+  </div><!-- .tab-content -->
+</div><!-- .tabs -->
+```
+
+**Step 3: Commit**
+
+```bash
+git add admin/js/views/pro-docs.js admin/js/templates/pro-docs.html
+git commit -m "feat: add Pro Documentation admin view and template"
+```
+
+---
+
+## Task 7: Wire the view into the admin SPA
+
+**Files:**
+- Modify: `admin/js/views/index.js`
+- Modify: `admin/js/app.js`
+- Modify: `admin/js/config/sidebar-config.js`
+
+**Step 1: Register the view in index.js**
+
+Add to `admin/js/views/index.js`:
+
+```js
+import {proDocsView} from './pro-docs.js';
+```
+
+Add to the `views` export object:
+```js
+proDocs: proDocsView,
+```
+
+**Step 2: Add the route in app.js**
+
+In the `coreRoutes` array in `admin/js/app.js`, add after the `actionEditor` route:
+
+```js
+{path: '/pro/docs', view: 'proDocs', title: 'Pro Documentation - Domma CMS'},
+```
+
+**Step 3: Add the sidebar entry in sidebar-config.js**
+
+In `admin/js/config/sidebar-config.js`, add a new "Pro" section after the Documentation section (after the `api-reference` item, before `return items`):
+
+```js
+  if (canStructure) {
+    items.push(
+      {divider: true},
+      {heading: 'Pro'},
+      {
+        id: 'pro-docs',
+        text: 'Documentation',
+        icon: 'zap',
+        url: '#/pro/docs',
+        section: '#/pro/docs'
+      }
+    );
+  }
+```
+
+**Step 4: Verify the route resolves**
+
+Navigate to `http://localhost:4096/admin/#/pro/docs` in a browser (or check the server doesn't 404 on it - it's
+client-side routing so the server always returns the admin shell).
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://localhost:4096/admin/
+```
+Expected: `200`
+
+**Step 5: Commit**
+
+```bash
+git add admin/js/views/index.js admin/js/app.js admin/js/config/sidebar-config.js
+git commit -m "feat: wire Pro Documentation into admin SPA routes and sidebar"
+```
+
+---
+
+## Verification Checklist
+
+1. `curl http://localhost:4096/resources/pro` → 200, renders hero + 3 cards
+2. `curl http://localhost:4096/resources/pro/views` → 200, contains aggregation pipeline docs
+3. `curl http://localhost:4096/resources/pro/actions` → 200, contains step types table
+4. `curl http://localhost:4096/resources/pro/cta` → 200, contains `[cta]` syntax
+5. `curl http://localhost:4096/resources` → contains "Pro Features" card text
+6. Admin at `#/pro/docs` → three tabs render (Views, Actions, CTA Shortcode), icons and syntax highlighting active
+7. Admin sidebar → "Pro" heading with "Documentation" link visible for admin/manager roles