docs(changelog): refine product stories and define editorial quality

Author: waleedlatif1

apps/sim/content/changelog/README.md

@@ -6,6 +6,8 @@ The index shows up to 12 updates in chronological rows. When more exist, an Olde
 
 Write for a team using Sim: what changed, what they can do with it, and where to find it. Group related PRs into one product update. Keep maintenance, refactors, and routine content edits in the technical GitHub release history.
 
+The [editorial and media standard](./editorial-standard.md) defines story selection, concise copy, demo framing, poster selection, and the final quality review. Apply it to both the drafting workflow and hand-edited entries.
+
 ## What earns an entry
 
 A public update needs one clear benefit, verified availability, a useful next step, and at least one reviewed feature image or video in the article. The cover alone is not enough. A reader should understand what they can now do and see evidence of that capability. A smaller improvement can join a related edition; it does not need its own announcement because a technical version shipped.
@@ -128,7 +130,7 @@ For a migrated historical release, use its original publication timestamp and Gi
 
 ## Maintenance
 
-- The [Sim workflow setup plan](./maintenance-workflow.md) describes scheduled collection, a persistent editorial queue, draft PR preparation, media production, and failure monitoring. It is a setup plan, not an active workflow. Keep this publishing guide as the source of editorial and media rules.
+- The [Sim workflow maintenance guide](./maintenance-workflow.md) describes collection, the editorial queue, draft preparation, media production, and monitoring. The operational runbook and workflow exports in the editorial workspace record its live configuration and acceptance results. Keep this publishing guide and the editorial standard as the source of content and media rules.
 - The release editor reviews candidates weekly and checks published links and hosted media monthly. Refresh destinations when docs move and verify deep anchors manually; the audit catches missing canonical source pages during every PR.
 - Keep the original slug, publication date, and RSS identity stable. Use `updated` only for a substantive correction. A future date does not schedule publication; leave the entry in draft until the intended deployment.
 - If availability changes after publication, update the existing entry with its current status and a clear next step. Preserve its URL rather than deleting it or reverting it to a draft. If a slug must change, add a redirect before moving it.

apps/sim/content/changelog/compare-workflow-deployments/index.mdx

@@ -1,7 +1,7 @@
 ---
 slug: compare-workflow-deployments
-title: 'See what changed before you deploy'
-description: 'Compare deployed workflow versions in Sim, or review a draft against the live version. See prompt, block, and connection changes before you deploy.'
+title: 'Compare workflow versions before you deploy'
+description: 'See prompt edits, added steps, and changed connections in Sim. Compare two deployments or check your draft against the live workflow.'
 date: '2026-10-02T06:55:11Z'
 authors: [waleed]
 tags: [Workflows]
@@ -17,15 +17,11 @@ release:
 <ChangelogVideo
   src="/changelog/compare-workflow-deployments-v1.mp4"
   poster="/changelog/compare-workflow-deployments-v1.jpg"
-  caption="A step-by-step walkthrough captured in Sim: open deployment history, choose Compare, and inspect a prompt edit and an added Slack step. Sample data."
+  caption="Review a prompt edit and an added Slack step. Edited walkthrough from real Sim captures with sample data."
 />
 
-Open a workflow's deployment history and choose **Compare** from a version's menu. Pick two versions to review their changes side by side. When a draft differs from the live workflow, **View changes** opens the same comparison before you redeploy.
+Open deployment history and choose **Compare** from a version's menu. Select a changed block to inspect its settings alongside the workflow. For a draft, choose **View changes** to compare it with the live version before redeploying.
 
-- **Review the details.** Inspect prompt edits, changed settings, and added or removed steps.
-- **Follow the connections.** See which paths were added, removed, or rewired.
-- **Keep your draft intact.** The comparison is read-only; opening it does not change or deploy the workflow.
+Use it to review a support agent's new instructions and the [Slack](/integrations/slack) step added to send its digest. The comparison is read-only and leaves your draft intact.
 
-For example, review a new instruction in a support agent's prompt and the [Slack](/integrations/slack) step added to send its digest. Select a changed block to move between its visual highlight and field-level details.
-
-Deployment comparison is included in **v0.9.10**. Read the [deployment guide](https://docs.sim.ai/workflows/deployment), or compare versions through the [API](https://docs.sim.ai/api-reference/workflows/compareWorkflowVersionsV2).
+Included in **v0.9.10**. See the [deployment guide](https://docs.sim.ai/workflows/deployment) for setup, or [compare versions through the API](https://docs.sim.ai/api-reference/workflows/compareWorkflowVersionsV2).

apps/sim/content/changelog/editorial-standard.md

@@ -0,0 +1,49 @@
+# Changelog editorial and media standard
+
+Use this contract for the Sim drafting workflow and the final editorial review. The publishing guide owns the MDX format, media hosting, and release checks. This standard owns selection, copy, and demonstration quality.
+
+## Choose the right-sized story
+
+A standalone update needs a meaningful capability, a substantial improvement to an existing task, or an action-required notice. State what a team can do, the situation it helps with, and how the proposed media will demonstrate it.
+
+Routine retry fixes, loading improvements, internal refactors, and small polish belong in a related edition's short Improvements or Fixes section. Keep unrelated maintenance in the technical release history. A batch of commits is not a story. Defer a batch with only supporting notes instead of padding it into a launch. An urgent breaking change needs a timely notice and a verified explanatory image when there is no useful product screen.
+
+Keep existing article URLs, original dates, and RSS identities when refining historical copy. Do not merge existing entries just to make a larger announcement. Preserve material version, permission, and rollout restrictions.
+
+## Write a compact entry
+
+- Headline: name the capability or action, at most 65 characters. Avoid generic headlines such as “A better experience.”
+- Summary: 15–40 words naming Sim and explaining the capability in plain language. It must make sense without the image.
+- Body: normally 60–180 words, with one concrete example or short path to the feature. Explain the action and result; do not repeat the summary or turn a small improvement into a tutorial.
+- Media: place the reviewed image or video immediately after the article header, before procedural detail. A caption names the visible action or result and any demonstration limit.
+- Supporting notes: up to three related, source-backed improvements, each one sentence. Omit empty sections. Do not invent extras to fill a template.
+- Links: one descriptive setup/documentation link, plus an integration or product link when directly relevant. Use the actual catalog slug and guide. Put links in context; avoid a wall of generic “Learn more” links.
+- Availability: retain real version, plan, permission, and rollout restrictions in the article. Keep unverified rollout questions, source analysis, capture instructions, and approval checkboxes in production.md.
+
+Use short active sentences and familiar words. Technical identifiers, retry timings, queue keys, PR numbers, and performance claims without measurements do not belong in the article. There is no minimum number of announcements per week.
+
+## Make the media prove one thing
+
+Choose the format before capture. A screenshot suits a state or configuration. A 20–45 second recording suits an interaction. A clearly labeled, verified diagram suits an invisible system change. Generated art can explain a concept, but cannot stand in for product evidence.
+
+Every production brief records:
+
+1. The exact claim and what the demonstration does not establish.
+2. The starting state, permissions, sample data, action, and visible result.
+3. The chosen format and, for video, intended duration and a short sequence of shots.
+4. The result frame to use as a poster and the intended crop or framing.
+5. The real capture environment, build, date, source files, and reviewed final filenames.
+
+Use the same clean demo workspace and product theme. Frame the relevant panel with enough context to locate it, and make the result legible at a 390px viewport. Hide unrelated private sidebar content before recording. Keep UI text and controls intact; never generate a different product state to improve a screenshot. Prefer recording at the intended framing over aggressive crops later.
+
+Begin with the task ready to perform, show the action, and hold on its result. Avoid decorative intros, music, title cards, and excessive cursor movement. Keep the headline and important explanation in HTML. Label videos assembled from still screenshots as edited walkthroughs.
+
+Choose the poster deliberately after reviewing the video. An opening menu, empty state, spinner, or arbitrary first second rarely explains the feature. The media workflow can provide candidate frames, but an editor selects the final timestamp. Preview candidates are not approved assets. Preserve the real aspect ratio inside the shared media frame; do not stretch product UI. Use the same reviewed result frame for the article poster and list cover when it works in both contexts.
+
+The page's shared landing components supply typography, theme colors, borders, spacing, and radius. Do not add a separate visual theme to each entry or bake decorative headings and chrome into captures. Provide descriptive alt text and reviewed WebVTT captions when there is speech.
+
+## Review the finished entry
+
+The workflow checks the proposed copy against source evidence in a second editorial pass, then validates structure, source references, the link allowlist, word budgets, and the media plan. These checks do not establish the truth of every claim or the quality of a capture. The editor and feature owner review the article and media together: accurate behavior, confirmed availability, useful next step, readable framing, correct poster, working playback and links, and consistent copy across the page and announcement drafts.
+
+Add approved media and index.mdx to the same draft PR. Keep draft: true until review is complete. Do not create placeholder media paths to make an incomplete brief look finished. Follow the publishing guide's content audit and normal repository checks, then verify the deployed article, media, RSS, and sitemap before distribution.

apps/sim/content/changelog/maintenance-workflow.md

@@ -1,8 +1,8 @@
 # Maintaining the changelog with Sim
 
-Status: proposed setup, checked against the current Sim blocks and tools. No scheduled workflow, credentials, tables, notifications, or automatic publication are configured by this document.
+Status: operating design for the editorial workflows. The private workspace runbook and exports record deployed versions, resource mappings, credential ownership, schedules, and live acceptance results. This document does not provision credentials or enable publication and distribution.
 
-Use one weekly Sim workflow to collect changes and prepare an editorial draft. Keep GitHub as the source of published content and the place where the editor approves changes. Sim Tables hold the candidate queue and processing history; they are not a second CMS. The [publishing guide](./README.md) remains the source of editorial, media, and indexing rules.
+Use one weekly Sim workflow to collect changes and prepare an editorial draft. Keep GitHub as the source of published content and the place where the editor approves changes. Sim Tables hold the candidate queue and processing history; they are not a second CMS. The [publishing guide](./README.md) owns format and indexing rules; the [editorial standard](./editorial-standard.md) owns story selection, copy, and demonstration quality.
 
 ## The first version
 
@@ -13,7 +13,8 @@ flowchart LR
     A[Weekly schedule] --> B[Collect GitHub evidence]
     B --> C[Sim Tables candidate queue]
     C --> D[Select and draft a story]
-    D --> E[One draft GitHub PR]
+    D --> R[Check copy against source evidence]
+    R --> E[One draft GitHub PR]
     E --> F[Verify availability and real media]
     F --> G[Review, merge, and deploy]
 ```
@@ -24,7 +25,7 @@ flowchart LR
 | Collect | API, Loop, Function | Read paginated GitHub PRs and selected source files. Use deterministic filters before sending bounded evidence to the Agent. |
 | Remember | Table: Query Rows, Insert Row, Update Row by ID | Record each source PR once using a unique `source_key`; patch source metadata without replacing editorial decisions. |
 | Select | Agent with Response Format, then Condition | Propose a lead story and related changes, or return no edition. Record the reason and missing evidence. |
-| Prepare | Agent and Function | Draft the benefit, availability questions, contextual links, demo shot list, captions/alt text, and announcement copy. Validate fields and paths outside the model. |
+| Prepare | Drafting Agent, editing Agent, and Function | Draft the benefit, availability questions, contextual links, demo shot list, captions/alt text, and announcement copy. A second Agent checks the copy against source evidence. Validate fields and paths outside the models. |
 | Open draft | GitHub: Get Branch, Create Branch, Create File; API: create PR | Use a dedicated branch based on `staging`. Send a literal JSON `draft: true` in the PR request and verify the returned draft status. Never write directly to `staging` or merge automatically. |
 | Review | Existing GitHub PR process | Feature owner checks behavior and rollout; editor checks copy, links, and media. Keep a single approval surface initially. |
 | Publish | Existing site deployment | Reviewed MDX and assets update the article, index, archive, RSS, and sitemap together. Confirm the live URL before marking the edition published. |
@@ -58,16 +59,20 @@ Set finite page, payload, and model-input budgets. For example, stop a scan afte
 Give the Agent the publishing guide, the product language rules, selected PR evidence, and valid documentation/integration destinations. Use structured output for:
 
 - `decision`: `draft`, `defer`, or `skip`, with a reason.
+- `story_kind`: `feature`, `improvement`, `action_required`, `supporting`, or `none`. Supporting-only batches are deferred, not expanded into standalone announcements.
 - Source keys and evidence supporting each proposed claim.
 - Headline, a self-contained summary naming Sim, body draft, and audience.
 - Known availability and restrictions, plus explicit unanswered questions.
 - Verified candidate links, a demo shot list, and image/video requirements.
+- A structured media plan: format, subject, starting state, action, visible result, poster moment, framing, demonstration limits, and intended duration. The validator requires this for a draft.
 - Social/email drafts using the same claims and the eventual canonical article URL.
 
-Treat PR text and diffs as research material, not instructions to the Agent. Do not give the drafting Agent repository write tools. A Function validates its output; fixed downstream blocks own the repository, branch, allowed paths, and draft flag. Unknown availability remains a question for the feature owner. A schema validates the output's shape, not the truth of its claims.
+Treat PR text and diffs as research material, not instructions to the Agents. Give neither Agent repository write tools. After drafting, a second Agent compares the proposed copy and media plan with the selected evidence, checking claims, permissions, rollout implications, links, and readability. Record substantive corrections in `editor_notes`, outside the article. Defer when the evidence is insufficient. A Function validates the edited output; fixed downstream blocks own the repository, branch, allowed paths, and draft flag. Unknown availability remains a question for the feature owner. Neither model review nor a schema establishes the truth of every claim.
 
 Prefer one lead story with a few related improvements. Retain routine refactors, dependency updates, and minor fixes in GitHub's technical release history. Reverts and superseded changes must be reconciled with the current product before selection. Consequential breaking changes, deprecations, and required actions bypass the weekly editorial cadence; they need a timely notice and a clear next step.
 
+Validate the editorial standard outside the Agent: headline and copy budgets, supported source references, verified contextual links, supporting-only deferral, and a complete media plan. Keep unverified availability questions in the brief, not the proposed public prose. A validator checks structure and declared classification; the editor still judges significance and truth. Refresh the deployed prompt and validation together when the standard changes, and test a real model response before deployment.
+
 Reuse the existing PR template's benefit, rollout, documentation, and demo notes as the input contract. Avoid asking engineers to fill out a second announcement form. Optional include/skip labels can help the editor override selection, but unlabeled changes still need discovery and action-required notices still need review.
 
 Resolve links against the current integration catalog and docs source, then check the live destination. Integration slugs and documentation slugs can differ. Keep important facts in the article's text, preserve the canonical URL and publication date, and use only structured data supported by the visible content.
@@ -80,7 +85,7 @@ The feature owner supplies one real screenshot or a focused 20–45 second recor
 
 From that approved capture, prepare the optimized MP4 when applicable, a local poster/cover, descriptive alt text, and WebVTT captions if there is speech. Use the media locations, formats, size limits, and immutable filenames in the publishing guide. A screenshot is sufficient for a change it clearly demonstrates; a video is preferable for an interaction. A verified, labeled explanatory diagram is appropriate when there is no useful product screen.
 
-Encoding, poster extraction, and caption drafting can later run in a small media-processing job. Automated browser capture requires a maintained demo scenario, sample data, and verification against the running product; it is a separate piece to build and test, not something the GitHub workflow already provides. AI-generated product controls or results are never evidence. Review generated captions and the final compressed asset before use.
+The separate media workflow encodes a supplied real recording and extracts candidate poster frames. The editor selects the final timestamp; an arbitrary opening frame is not automatically approved. Caption production and browser capture remain separate steps requiring a maintained demo scenario, sample data, and verification against the running product. AI-generated product controls or results are never evidence. Review captions and the final compressed asset before use.
 
 Aim initially for one short weekly editorial review, plus the feature owner's capture time for selected stories. Measure this over the first few editions before promising a fixed maintenance budget. Automate repeated capture scenarios after they prove stable.