@almadar/std 16.191.0 → 16.193.0

package/behaviors/lolo/infra/atoms/std-approval-gate.lolo

@@ -1,5 +1,5 @@
-app std-approval-gate "1.0.1"
-"std-approval-gate — generic approval gate / approver workflow. Use when a user voices that an action must be reviewed, approved, signed off, or authorized by a privileged role before it proceeds (admin approval, supervisor sign-off, manager approval, gatekeeper review, editor approval, senior editor approval, reviewer approval, publishing approval, draft approval, content review, submit drafts then editors review and approve or reject, needs approval before going live, requires sign-off before publish). Persists ApprovalRequest rows + surfaces them in a review queue with Approve / Deny / Reject actions, optionally requiring a written rejection reason or feedback comment. On approval emits ApprovalGranted; on denial emits ApprovalDenied. Compose onto any orbital whose action you want to gate: the target orbital emits an external event, an ApprovalRequest row is created, and downstream effects wait on ApprovalGranted. Differs from std-mod-queue, which is content-moderation-specific."
+app std-approval-gate "1.1.0"
+"std-approval-gate — generic approval gate / approver workflow. Use when a user voices that an action must be reviewed, approved, signed off, or authorized by a privileged role before it proceeds (admin approval, supervisor sign-off, manager approval, gatekeeper review, editor approval, senior editor approval, reviewer approval, publishing approval, draft approval, content review, submit drafts then editors review and approve or reject, needs approval before going live, requires sign-off before publish). Persists ApprovalRequest rows + surfaces the PENDING ones in a review queue showing what is being approved and who asked, with Approve / Deny actions — Deny captures a written reason. approverRoles is ENFORCED by the review transitions themselves: an APPROVE/DENY from a viewer whose role is not listed does not fire. On approval emits ApprovalGranted; on denial emits ApprovalDenied (with the reason). Hosts that replay the gated action MUST route a failed replay back via APPROVAL_REPLAY_FAILED so the request reopens instead of being silently consumed. Compose onto any orbital whose action you want to gate: the target orbital emits an external event, an ApprovalRequest row is created (stamp subjectLabel/subjectId/requestedBy so reviewers see what they are judging), and downstream effects wait on ApprovalGranted. Differs from std-mod-queue, which is content-moderation-specific."
 orbital ApprovalGateOrbital {
     uses Spinner from "std/behaviors/ui-spinner"
     uses Typography from "std/behaviors/ui-typography"
@@ -18,17 +18,34 @@ orbital ApprovalGateOrbital {
 
     type ApprovalGranted = Event { requestId : string, payload : object } "Re-emitted on approval; carries the held payload so the downstream listener can replay the gated action without a lookup."
 
-    type ApprovalDenied = Event { requestId : string } "Emitted on denial; downstream listeners can log or notify."
+    type DenyCommit = { id : string!, notes : string }
 
+    type ApprovalDenied = Event { requestId : string, reason : string } "Emitted on denial; carries the reviewer's written reason. Downstream listeners log, notify, or return the subject to its prior state."
+
+  ;; The queue is a shared review surface — every signed-in role may need to
+  ;; SEE what is pending about their own submissions; WHO may decide is the
+  ;; role guard on the APPROVE/DENY transitions (the FSM enforces it on the
+  ;; affordance and on any bus-delivered event alike). Entity-layer access
+  ;; predicates CANNOT live here: a generic atom declares no [identity]
+  ;; entity, and ORB_S_ACCESS_POLICY_REQUIRES_IDENTITY (correctly) rejects a
+  ;; @user-reading directive without a roster — while a host cannot add
+  ;; predicates to a foreign atom's entity. Ledgered
+  ;; (R-APPROVAL-REQUEST-ENTITY-LAYER-UNGATED); the guard layer above is the
+  ;; enforcement both paths carry today.
   entity ApprovalRequest [persistent: approval_requests] {
+    @read none "Shared review surface: submitters watch their requests, approvers work the queue; decision authority is enforced at the transitions, not by hiding rows."
     id : string!
     gatedEvent : string @description "The event that triggered the approval request." @synonyms "trigger, event, source" = ""
+    subjectLabel : string @description "Human title of the thing being approved (the article's headline, the page's title) — what the reviewer sees in the queue." @synonyms "title, subject, what is being approved" = ""
+    subjectId : string @description "Id of the record being approved, for a queue row's View click-through to the subject's own surface." @synonyms "record id, target id, article id, page id" = ""
+    requestedBy : string @description "User id of the submitter." @synonyms "submitter, author, requester id" = ""
+    requestedByName : string @description "Display name of the submitter shown in the queue." @synonyms "submitter name, requester, who asked" = ""
     status : "pending" | "approved" | "denied" | "escalated" @description "Current state of the approval process." @synonyms "approval status, state, condition" = pending
     reviewer : string @description "The user or system responsible for reviewing the request." @synonyms "assignee, owner, approver, responsible party" = ""
     requestedAt : number @description "Timestamp indicating when the approval request was initiated." @synonyms "creation time, request date, submission time" = 0
     decidedAt : number @description "Timestamp indicating when a decision was made on the request." @synonyms "decision time, resolved at, completed at" = 0
     escalatedAt : number @description "Timestamp indicating when the request was escalated." @synonyms "escalation time, escalation timestamp, escalated time" = 0
-    notes : string @description "Free-form text providing additional context or details." @synonyms "comments, remarks, explanation, details" = ""
+    notes : string @description "The reviewer's written reason, captured by the deny step." @synonyms "comments, remarks, explanation, reason, details" = ""
     payload : object @description "The held data of the gated action, replayed by the downstream listener when the request is granted." @synonyms "request data, held payload, pending data, gated data" = {}
   }
 
@@ -63,6 +80,21 @@ orbital ApprovalGateOrbital {
     }
   }
 
+  trait DenyReasonTitle = Typography.traits.TypographyRender -> ApprovalRequest {
+    config {
+      content: "Deny request"
+      variant: h3
+    }
+  }
+
+  trait DenyReasonHint = Typography.traits.TypographyRender -> ApprovalRequest {
+    config {
+      color: muted
+      content: "Tell the submitter why — the reason is recorded on the request."
+      variant: caption
+    }
+  }
+
   trait CloseButton = Button.traits.ButtonRender -> ApprovalRequest {
     config {
       action: CLOSE
@@ -86,15 +118,30 @@ orbital ApprovalGateOrbital {
   trait ApprovalGateReview -> @rebindable ApprovalRequest [interaction, collection, approval] {
     initial: idle
 
+    ;; Every queue fetch is scoped to PENDING rows: a decided row must leave
+    ;; the queue, or its still-live Approve action re-emits ApprovalGranted
+    ;; with the ORIGINAL payload and replays a stale edit over current state.
     state idle {
       INIT -> idle
         (fetch ApprovalRequest {
+          filter: ["=", (object/get @entity status), "pending"]
           emit: { failure: ApprovalRequestLoadFailed, success: ApprovalRequestLoaded }
         })
       ApprovalRequestLoaded -> idle
       ApprovalRequestLoadFailed -> idle
+      ;; A replay failure can also arrive while the queue is closed.
+      APPROVAL_REPLAY_FAILED -> idle
+        (set @entity.id ?requestId)
+        (set @entity.status pending)
+        (set @entity.reviewer "")
+        (set @entity.decidedAt 0)
+        (persist update ApprovalRequest @entity {
+          emit: { failure: ApprovalRequestReviewFailed, success: ApprovalRequestReviewed }
+        })
+        (notify "Approval could not be applied — the request was reopened." error)
       OPEN -> loading when @config.enabled
         (fetch ApprovalRequest {
+          filter: ["=", (object/get @entity status), "pending"]
           emit: { failure: ApprovalRequestLoadFailed, success: ApprovalRequestLoaded }
         })
         (render-ui @config.reviewSlot {
@@ -127,20 +174,29 @@ orbital ApprovalGateOrbital {
             cols: 1
             entity: ?data
             fields: [{
+              label: What
+              name: subjectLabel
+              variant: h4
+            }, {
               label: Action
               name: gatedEvent
               variant: badge
+            }, {
+              label: "Requested by"
+              name: requestedByName
+              variant: caption
             }, {
               label: Requested
               name: requestedAt
               variant: caption
-            }, {
-              label: Status
-              name: status
-              variant: badge
             }]
             gap: sm
             itemActions: [{
+              event: OPEN_SUBJECT
+              icon: eye
+              label: View
+              variant: ghost
+            }, {
               event: APPROVE
               icon: check
               label: Approve
@@ -168,27 +224,92 @@ orbital ApprovalGateOrbital {
     }
 
     state reviewing {
-      APPROVE -> reviewing
+      ;; The role guard IS the enforcement (both execution paths honor
+      ;; transition guards, for the button and for a bus-delivered event
+      ;; alike): empty approverRoles = ungated, otherwise the viewer's role
+      ;; must be listed or the decision does not fire.
+      APPROVE -> reviewing when (or ["=", (array/len @config.approverRoles), 0] (array/includes @config.approverRoles @user.role))
         (set @entity.id ?id)
         (set @entity.status approved)
         (set @entity.reviewer @user.id)
+        (set @entity.decidedAt (time/now))
         (persist update ApprovalRequest @entity {
           emit: { failure: ApprovalRequestReviewFailed, success: ApprovalRequestReviewed }
         })
         (emit ApprovalGranted { payload: ?row.payload, requestId: ?id })
-      DENY -> reviewing
+      ;; Deny is a two-step: capture the written reason first, commit second.
+      DENY -> denying when (or ["=", (array/len @config.approverRoles), 0] (array/includes @config.approverRoles @user.role))
         (set @entity.id ?id)
+        (set @entity.subjectLabel (str/default (object/get ?row subjectLabel) ""))
+        (render-ui @config.reviewSlot {
+          children: [{
+            align: center
+            children: [@trait.DenyReasonTitle, @trait.CloseButton]
+            direction: horizontal
+            gap: sm
+            justify: between
+            type: stack
+          }, @trait.DenyReasonHint, @trait.ApprovalDivider, {
+            cancelEvent: CANCEL_DENY
+            entity: { id: @entity.id }
+            fields: (notes)
+            mode: edit
+            submitEvent: CONFIRM_DENY
+            type: form-section
+          }]
+          direction: vertical
+          gap: md
+          type: stack
+        })
+      OPEN_SUBJECT -> reviewing
+      ApprovalRequestReviewed -> loading
+        (fetch ApprovalRequest {
+          filter: ["=", (object/get @entity status), "pending"]
+          emit: { failure: ApprovalRequestLoadFailed, success: ApprovalRequestLoaded }
+        })
+      ApprovalRequestReviewFailed -> reviewing
+        (render-ui @config.reviewSlot {
+          children: [@trait.ErrorAlert]
+          type: stack
+        })
+      ;; A host reports the gated action could not be applied after approval
+      ;; (an entity-access denial, a failed write): reopen the request so it
+      ;; is never silently consumed.
+      APPROVAL_REPLAY_FAILED -> reviewing
+        (set @entity.id ?requestId)
+        (set @entity.status pending)
+        (set @entity.reviewer "")
+        (set @entity.decidedAt 0)
+        (persist update ApprovalRequest @entity {
+          emit: { failure: ApprovalRequestReviewFailed, success: ApprovalRequestReviewed }
+        })
+        (notify "Approval could not be applied — the request was reopened." error)
+      CLOSE -> idle
+        (render-ui @config.reviewSlot null)
+    }
+
+    state denying {
+      CONFIRM_DENY -> reviewing
+        (set @entity.id (object/get ?data id))
         (set @entity.status denied)
         (set @entity.reviewer @user.id)
+        (set @entity.decidedAt (time/now))
+        (set @entity.notes (str/default (object/get ?data notes) ""))
         (persist update ApprovalRequest @entity {
           emit: { failure: ApprovalRequestReviewFailed, success: ApprovalRequestReviewed }
         })
-        (emit ApprovalDenied { requestId: ?id })
+        (emit ApprovalDenied { requestId: (object/get ?data id), reason: (str/default (object/get ?data notes) "") })
+      CANCEL_DENY -> loading
+        (fetch ApprovalRequest {
+          filter: ["=", (object/get @entity status), "pending"]
+          emit: { failure: ApprovalRequestLoadFailed, success: ApprovalRequestLoaded }
+        })
       ApprovalRequestReviewed -> loading
         (fetch ApprovalRequest {
+          filter: ["=", (object/get @entity status), "pending"]
           emit: { failure: ApprovalRequestLoadFailed, success: ApprovalRequestLoaded }
         })
-      ApprovalRequestReviewFailed -> reviewing
+      ApprovalRequestReviewFailed -> denying
         (render-ui @config.reviewSlot {
           children: [@trait.ErrorAlert]
           type: stack
@@ -200,6 +321,7 @@ orbital ApprovalGateOrbital {
     state error {
       OPEN -> loading
         (fetch ApprovalRequest {
+          filter: ["=", (object/get @entity status), "pending"]
           emit: { failure: ApprovalRequestLoadFailed, success: ApprovalRequestLoaded }
         })
         (render-ui @config.reviewSlot {
@@ -222,9 +344,27 @@ orbital ApprovalGateOrbital {
         id : string!
         row : ApprovalRequest
       }
-        @description "Signals that an approval request has been denied."
+        @description "Opens the deny step for a request; the decision commits with the written reason."
         @synonyms "reject, decline"
         @tier "domain"
+      OPEN_SUBJECT -> external {
+        id : string!
+        subjectId : string
+        subjectLabel : string
+      }
+        @description "A reviewer clicked View on a queue row. Hosts route subjectId to the subject record's own surface so the reviewer can read what they are approving. Scalars only — the row stays in the queue."
+        @synonyms "view subject, open record, inspect request, see the article"
+        @tier "domain"
+      CONFIRM_DENY {
+        data : DenyCommit
+      }
+        @description "The deny form committed; data carries the request id + the written reason."
+        @synonyms "submit denial, confirm rejection"
+        @tier "internal"
+      CANCEL_DENY
+        @description "The deny form was dismissed without committing; the queue repaints."
+        @synonyms "cancel denial, back to queue"
+        @tier "internal"
       CLOSE
         @description "Dismisses the review queue overlay."
         @synonyms "dismiss, hide, cancel, done"
@@ -233,13 +373,14 @@ orbital ApprovalGateOrbital {
         requestId : string
         payload : object
       }
-        @description "Signals that an approval process has been successfully completed; carries the held payload for the downstream listener to replay."
+        @description "Signals that an approval process has been successfully completed; carries the held payload for the downstream listener to replay. Contract: if the replay fails (access denial, write failure), the host MUST emit APPROVAL_REPLAY_FAILED back so the request reopens."
         @synonyms "approved, authorized, confirmed, validated"
         @tier "domain"
       ApprovalDenied -> external {
         requestId : string
+        reason : string
       }
-        @description "Indicates an approval request has been denied."
+        @description "Indicates an approval request has been denied, with the reviewer's written reason."
         @synonyms "rejected, declined"
         @tier "domain"
       ApprovalRequestLoaded {
@@ -291,9 +432,34 @@ orbital ApprovalGateOrbital {
         id : string!
         row : ApprovalRequest
       }
-        @description "Indicates an approval request has been rejected."
+        @description "Opens the deny step for a request."
         @synonyms "reject, decline, deny"
         @tier "domain"
+      OPEN_SUBJECT {
+        id : string!
+        subjectId : string
+        subjectLabel : string
+      }
+        @description "A reviewer asked to view the subject of a queue row; the host routes the navigation."
+        @synonyms "view subject, open record, inspect"
+        @tier "domain"
+      CONFIRM_DENY {
+        data : DenyCommit
+      }
+        @description "The deny form committed with the written reason."
+        @synonyms "submit denial, confirm rejection"
+        @tier "internal"
+      CANCEL_DENY
+        @description "The deny form was dismissed; return to the queue."
+        @synonyms "cancel denial, back"
+        @tier "internal"
+      APPROVAL_REPLAY_FAILED {
+        requestId : string!
+        error : string
+      }
+        @description "The host could not apply the granted action (access denial, failed write). The request reopens as pending so a decision is never silently lost."
+        @synonyms "replay failed, apply failed, approval rollback"
+        @tier "domain"
       ApprovalRequestLoaded {
         data : [ApprovalRequest]
       }
@@ -330,7 +496,7 @@ orbital ApprovalGateOrbital {
         @tier "policy"
       approverRoles : [string] = []
         @label "Who can approve requests?"
-        @description "Roles eligible to approve. The host application enforces role-gating on the page."
+        @description "Roles eligible to decide. ENFORCED by the APPROVE/DENY transition guards: a viewer whose @user.role is not listed cannot fire a decision, from the button or from the bus. Empty = every signed-in viewer may decide (ungated)."
         @synonyms "approver, reviewer, authorized roles, sign-off roles, who approves"
         @tier "policy"
       threshold : number = 0
@@ -370,4 +536,4 @@ orbital ApprovalGateOrbital {
   }
 
   page "/approvals/queue" as ApprovalGateReviewPage -> ApprovalGateReview
-}
+}

package/behaviors/lolo/infra/atoms/std-status-lifecycle.lolo

@@ -20,9 +20,14 @@ orbital StatusLifecycleOrbital {
     state idle {
       ChangeStatusRequested -> idle when (and @config.enabled (array/some @config.transitions (fn t (and ["=", (object/get @t from), ?from] ["=", (object/get @t to), ?to]))))
         (persist update @config.targetEntity (object/set { id: ?id } @config.statusField ?to) {
-          emit: { failure: StatusChangeFailed, success: StatusChanged }
+          emit: { failure: StatusChangeFailed, success: StatusPersisted }
         })
-        (emit StatusChanged { entityId: ?id, status: ?to })
+      ;; StatusChanged is re-emitted ONLY off the persist's success (guarded
+      ;; on ?id against the optimistic/authoritative double-fire) — the old
+      ;; synchronous emit fired even when the write failed, so a denied
+      ;; mutation still looked like a completed transition downstream.
+      StatusPersisted -> idle when ["!=", (str/default ?id ""), ""]
+        (emit StatusChanged { entityId: ?id, status: (str/default (object/get ?row @config.statusField) "") })
       StatusChangeFailed -> idle
     }
 
@@ -31,7 +36,11 @@ orbital StatusLifecycleOrbital {
         entityId : string
         status : string
       }
-      StatusChangeFailed {
+      StatusPersisted {
+        id : string
+        row : StatusRecord
+      }
+      StatusChangeFailed -> external {
         error : string
         code : string
       }
@@ -43,6 +52,10 @@ orbital StatusLifecycleOrbital {
         from : string
         to : string
       }
+      StatusPersisted {
+        id : string
+        row : StatusRecord
+      }
       StatusChangeFailed {
         error : string
         code : string

package/behaviors/lolo/ui/core/atoms/std-app-layout.lolo

@@ -41,6 +41,7 @@ orbital AppLayoutOrbital {
             notificationClickEvent: @config.notificationClickEvent
             notifications: @config.notifications
             searchEvent: @config.searchEvent
+            sidebarContent: @config.sidebarTrait
             topBarActions: @config.topBarActions
             type: @config.layoutPattern
             user: (if @config.viewerName { avatar: @config.viewerAvatar, email: @config.viewerEmail, name: @config.viewerName } null)
@@ -90,6 +91,11 @@ orbital AppLayoutOrbital {
         @label "Content trait"
         @description "Trait rendered inside the app layout content area"
         @tier "presentation"
+      sidebarTrait : trait
+        @label "Sidebar trait"
+        @description "Optional trait rendered in the sidebar between the nav links and the footer — the Notion/Confluence-style always-visible page tree; scrolls independently. Unset renders plain nav only."
+        @synonyms "sidebar tree, nav tree, page tree in sidebar, hierarchy rail"
+        @tier "presentation"
       appName : string = App
         @label "What should this app be called?"
         @description "Name shown in the top-left of the chrome header."

package/behaviors/lolo/ui/core/atoms/std-billable-hour.lolo

@@ -30,6 +30,7 @@ orbital BillableHourOrbital {
       itemActions: @config.itemActions
       look: @config.tableLook
       maxInlineActions: 2
+      selfFetch: false
     }
 
     listens {

package/behaviors/lolo/ui/core/atoms/std-browse.lolo

@@ -38,6 +38,7 @@ orbital BrowseItemOrbital {
       itemActions: @config.itemActions
       maxInlineActions: @config.maxInlineActions
       pageSize: @config.displayPageSize
+      selfFetch: false
     }
 
     listens {
@@ -55,6 +56,7 @@ orbital BrowseItemOrbital {
       maxInlineActions: @config.maxInlineActions
       pageSize: @config.displayPageSize
       selectable: @config.selectable
+      selfFetch: false
     }
 
     listens {
@@ -69,6 +71,7 @@ orbital BrowseItemOrbital {
       itemClickEvent: @config.itemClickEvent
       maxInlineActions: @config.maxInlineActions
       variant: compact
+      selfFetch: false
     }
 
     listens {

package/behaviors/lolo/ui/core/atoms/std-image-upload-multi.lolo

@@ -1,6 +1,10 @@
 app std-image-upload-multi "1.0.0"
 "std-image-upload-multi — multi-image upload with drop zone, gallery preview, and per-batch progress."
 orbital UploadedImageOrbital {
+    type UploadBatchFile = { name : string!, size : number, type : string, content : string }
+
+    type StoredImageItem = { id : string!, key : string, url : string, name : string, sizeBytes : number, mimeType : string }
+
     type UploadedImageLoaded = Event { data : [UploadedImage] } "Fired when the uploaded-image collection finishes loading"
 
     type UploadedImageLoadFailed = Event { error : string, code : string } "Fired when the uploaded-image collection fails to load"
@@ -96,8 +100,13 @@ orbital UploadedImageOrbital {
           type: stack
         })
       UPLOAD -> uploading
-        (persist create UploadedImage ?files {
-          emit: { failure: UploadedImageUploadFailed, success: UploadedImageCreated }
+        (call-service storage uploadMany {
+          acl: public
+          bucket: @config.bucket
+          files: ?files
+          maxSize: @config.maxBytesPerImage
+        } {
+          emit: { failure: UploadedImageUploadFailed, success: UploadedImageStored }
         })
         (render-ui main {
           align: center
@@ -133,6 +142,12 @@ orbital UploadedImageOrbital {
     }
 
     state uploading {
+      ;; The storage service owns the bytes; rows persist only the returned
+      ;; addresses — ?items is shaped for this bulk create (url/name/sizeBytes/mimeType).
+      UploadedImageStored -> uploading
+        (persist create UploadedImage ?items {
+          emit: { failure: UploadedImageUploadFailed, success: UploadedImageCreated }
+        })
       UploadedImageCreated -> loading
         (fetch UploadedImage {
           emit: { failure: UploadedImageLoadFailed, success: UploadedImageLoaded }
@@ -192,7 +207,7 @@ orbital UploadedImageOrbital {
 
     emits {
       UPLOAD {
-        files : object!
+        files : [UploadBatchFile]!
       }
         @description "Signals that an image upload process has begun."
         @synonyms "start, initiate, begin"
@@ -216,6 +231,13 @@ orbital UploadedImageOrbital {
         @description "A new image has been successfully uploaded."
         @synonyms "added, new, received"
         @tier "domain"
+      UploadedImageStored {
+        items : [StoredImageItem]
+        count : number
+      }
+        @description "The storage service accepted the whole batch; items carry each file's stored address and metadata, ready to persist."
+        @synonyms "uploaded, stored, saved to storage"
+        @tier "internal"
       UploadedImageUploadFailed {
         error : string
         code : string
@@ -240,7 +262,7 @@ orbital UploadedImageOrbital {
 
     listens {
       UPLOAD {
-        files : object!
+        files : [UploadBatchFile]!
       }
         @description "Indicates a file upload has begun."
         @synonyms "start, begin, initiate"
@@ -270,6 +292,13 @@ orbital UploadedImageOrbital {
         @description "A new image has been successfully uploaded."
         @synonyms "added, received, new image"
         @tier "domain"
+      UploadedImageStored {
+        items : [StoredImageItem]
+        count : number
+      }
+        @description "The storage service accepted the batch; the items are persisted as uploaded-image rows."
+        @synonyms "uploaded, stored, saved to storage"
+        @tier "internal"
       UploadedImageUploadFailed {
         error : string
         code : string
@@ -309,6 +338,10 @@ orbital UploadedImageOrbital {
         @label "MIME filter"
         @description "Browser accept filter for the file picker"
         @tier "domain"
+      bucket : string = "images"
+        @label "Storage bucket"
+        @description "Object-storage bucket the batch uploads into"
+        @tier "domain"
     }
   }
 

package/behaviors/lolo/ui/core/atoms/std-record-detail.lolo

@@ -20,6 +20,8 @@ orbital RecordItemOrbital {
     status : "active" | "inactive" | "pending" @description "The record's current state." @synonyms "state, condition, stage" = active
     slug : string @description "URL-friendly identifier, for records opened by address instead of id." @synonyms "permalink, url key, address" = ""
     content : string @description "The record's rich-text body as HTML, edited in place by the document look." @synonyms "body, text, document, article body" = ""
+    coverUrl : string @intrinsic @description "The document look's cover/hero image URL, stamped from the loaded row's coverField." = ""
+    iconName : string @intrinsic @description "The document look's icon name, stamped from the loaded row's iconField." = ""
     loadedRow : object @intrinsic @description "The full row exactly as last fetched (relations hydrated when config.include asks). The details drawer binds it, and hosts that need it (e.g. a settings modal) stash it from RecordItemLoaded — the document panel itself takes only scalar props and emits scalar payloads ({ id, title })." = {}
     openDraft : string @intrinsic @description "Set from the navigate payload when the surface was opened on a record that was JUST minted blank; read once the row loads to decide whether the document body opens authoring (draft) or read-only. Absent on a refresh or a normal open, so the draft entry never repeats." @synonyms "new document, just created, draft open" = ""
     createdAt : string
@@ -128,6 +130,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get ?data @config.titleField))
         (set @entity.description (str/default (object/get ?data @config.subtitleField) ""))
         (set @entity.content (object/get ?data @config.contentField))
+        (set @entity.coverUrl (str/default (object/get ?data @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get ?data @config.iconField) ""))
         (render-ui main @config.documentEditingContent)
       RecordItemLoaded -> viewing when ["!=", (str/default (object/get @entity openDraft) ""), "1"]
         ;; (object/merge … {}) is a type adapter only: type_compat lacks "declared object accepts a named row type" (ledgered)
@@ -136,6 +140,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get ?data @config.titleField))
         (set @entity.description (str/default (object/get ?data @config.subtitleField) ""))
         (set @entity.content (object/get ?data @config.contentField))
+        (set @entity.coverUrl (str/default (object/get ?data @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get ?data @config.iconField) ""))
         (if ["=", @config.detailLook, document]
           (render-ui main @config.documentBodyContent)
           (if ["=", @config.detailLook, slide-over]
@@ -149,6 +155,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get (array/first ?data) @config.titleField))
         (set @entity.description (str/default (object/get (array/first ?data) @config.subtitleField) ""))
         (set @entity.content (object/get (array/first ?data) @config.contentField))
+        (set @entity.coverUrl (str/default (object/get (array/first ?data) @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get (array/first ?data) @config.iconField) ""))
         (render-ui main @config.documentEditingContent)
       RecordItemSlugLoaded -> viewing when (and [">", (array/len ?data), 0] ["!=", (str/default (object/get @entity openDraft) ""), "1"])
         (set @entity.loadedRow (array/first ?data))
@@ -156,6 +164,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get (array/first ?data) @config.titleField))
         (set @entity.description (str/default (object/get (array/first ?data) @config.subtitleField) ""))
         (set @entity.content (object/get (array/first ?data) @config.contentField))
+        (set @entity.coverUrl (str/default (object/get (array/first ?data) @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get (array/first ?data) @config.iconField) ""))
         (if ["=", @config.detailLook, document]
           (render-ui main @config.documentBodyContent)
           (if ["=", @config.detailLook, slide-over]
@@ -245,6 +255,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get ?data @config.titleField))
         (set @entity.description (str/default (object/get ?data @config.subtitleField) ""))
         (set @entity.content (object/get ?data @config.contentField))
+        (set @entity.coverUrl (str/default (object/get ?data @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get ?data @config.iconField) ""))
         (if ["=", @config.detailLook, document]
           (render-ui main @config.documentBodyContent)
           (if ["=", @config.detailLook, slide-over]
@@ -258,6 +270,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get (array/first ?data) @config.titleField))
         (set @entity.description (str/default (object/get (array/first ?data) @config.subtitleField) ""))
         (set @entity.content (object/get (array/first ?data) @config.contentField))
+        (set @entity.coverUrl (str/default (object/get (array/first ?data) @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get (array/first ?data) @config.iconField) ""))
         (if ["=", @config.detailLook, document]
           (render-ui main @config.documentBodyContent)
           (if ["=", @config.detailLook, slide-over]
@@ -507,6 +521,16 @@ orbital RecordItemOrbital {
         @description "Name of the field on the loaded record that carries the rich-text HTML body the document look renders and edits (e.g. content, body, articleText)."
         @synonyms "body field, content field, document field"
         @tier "presentation"
+      coverField : string = ""
+        @label "Which field is the cover image?"
+        @description "Name of the image-typed field on the loaded record painted as the document look's full-bleed hero banner (e.g. coverImage, heroImage). Empty = no banner, the default."
+        @synonyms "cover field, hero image field, banner field"
+        @tier "presentation"
+      iconField : string = ""
+        @label "Which field is the document icon?"
+        @description "Name of the field on the loaded record whose icon name renders beside the document title (e.g. icon). Empty = no icon, the default."
+        @synonyms "icon field, glyph field"
+        @tier "presentation"
       editLabel : string = "Edit"
         @label "Edit button label"
         @description "Label of the quiet button above the document body that starts an editing session (the body itself is also clickable)."
@@ -587,6 +611,8 @@ orbital RecordItemOrbital {
         @tier "internal"
       documentBodyContent : render-ui = {
         actions: @config.actions
+        coverImage: @entity.coverUrl
+        icon: @entity.iconName
         editEvent: EDIT_CONTENT
         editLabel: @config.editLabel
         id: @entity.id
@@ -604,6 +630,8 @@ orbital RecordItemOrbital {
         @tier "internal"
       documentEditingContent : render-ui = {
         actions: @config.actions
+        coverImage: @entity.coverUrl
+        icon: @entity.iconName
         autosaveHint: @config.autosaveHint
         contentChangeEvent: CONTENT_CHANGE
         doneEvent: DONE_EDITING
@@ -675,6 +703,14 @@ orbital RecordItemOrbital {
         @description "A property in the settings rail committed in place; patch carries the row id plus the one changed field, ready to hand straight to a persist update. Quiet contract: the host persists without refetching or repainting the open document."
         @synonyms "property saved, metadata changed, field committed, update property"
         @tier "domain"
+      RELATION_OPEN -> external {
+        field : string!
+        id : string!
+        name : string
+      }
+        @description "A relation chip in the details drawer was clicked (a tag, the author, the category); id is the linked row's id. Hosts route it to the linked record's own surface — a navigate, a scoped overlay, a filtered list."
+        @synonyms "open relation, linked record clicked, tag clicked, chip clicked"
+        @tier "domain"
     }
 
     listens {
@@ -718,6 +754,7 @@ orbital RecordItemOrbital {
       detailsContent : render-ui = {
         entity: @entity.loadedRow
         fields: @config.metaFields
+        relationEvent: RELATION_OPEN
         title: @config.detailsTitle
         type: document-details
       }