Document scheduled publishing for incidents and maintenance

v3.x/guide/incidents.mdx

@@ -11,6 +11,7 @@ the dashboard. Incidents consist of:
 - **Status**: The current status of the incident.
 - **Message**: A detailed description of the incident.
 - **Occurred At**: The time the incident occurred. This can be left empty if the incident happened at the time of reporting.
+- **Published At**: An optional time to publish the incident. While set in the future, the incident is hidden from the status page and public API until that moment. Leave it empty to publish immediately.
 - **Visibility**: Whether the incident should be visible to users, guests or always be hidden.
 - **Stickied**: Whether the incident is pinned to the top of your status page. Stickied incidents remain prominently displayed until you unsticky them.
 
@@ -28,6 +29,25 @@ Incidents and updates in Cachet can have one of the following statuses:
 - <Tooltip tip="Status ID: 3"><Icon icon="square-3" /></Tooltip> **Watching**: The incident or the resolution is being watched.
 - <Tooltip tip="Status ID: 4"><Icon icon="square-4" /></Tooltip> **Fixed**: The incident is fully resolved.
 
+## Scheduling publication
+
+Incidents don't have to go live the moment you create them. By setting a **Published At** date in the future, you can
+prepare an incident ahead of time and have it appear automatically when that time arrives.
+
+Until the published date passes, the incident is treated as a draft:
+
+- It is hidden from the status page and from public reads of the [API](/api-reference/introduction) — for guests and read-only API tokens alike.
+- It remains fully visible and editable in the dashboard, over the [MCP server](/v3.x/guide/mcp), and to API tokens with the `incidents.manage` ability, so you can review and adjust what you've prepared.
+- Any [subscriber notifications](/v3.x/guide/subscribers) are deferred — they are sent when the incident is published, not when it is created.
+
+Leave **Published At** empty (the default) to publish the incident immediately, preserving the usual behaviour.
+
+<Note>
+    Publication is evaluated in real time, so an incident appears the moment its published date passes. Subscriber
+    notifications are dispatched by the scheduled `cachet:publish-scheduled` command, so make sure Cachet's
+    [scheduler](/v3.x/installation) is running.
+</Note>
+
 ## Incident components
 
 Incidents don't typically occur in isolation. They often affect one or more [components](/v3.x/guide/components) of the service. Cachet allows you

v3.x/guide/schedules.mdx

@@ -13,6 +13,7 @@ A scheduled maintenance event consists of:
 - **Message**: A detailed description of the maintenance.
 - **Scheduled At**: The date and time when the maintenance will start.
 - **Completed At**: The date and time when the maintenance was completed.
+- **Published At**: An optional time to publish the maintenance. While set in the future, the maintenance is hidden from the status page and public API until that moment. Leave it empty to publish immediately.
 - **Components**: The [components](/v3.x/guide/components) affected by the maintenance, along with the status each should display while it's underway (typically **Under Maintenance**).
 - **Notify subscribers**: Whether to notify your [subscribers](/v3.x/guide/subscribers) about this maintenance, for example when it's rescheduled or completed.
 
@@ -24,6 +25,25 @@ Cachet automatically infers the status of a schedule based on the current date a
 - **In Progress**: The maintenance is currently in progress.
 - **Complete**: The maintenance has been completed.
 
+## Scheduling publication
+
+You can prepare maintenance well in advance without revealing it straight away. By setting a **Published At** date in the
+future, the maintenance stays a draft and appears automatically once that time arrives.
+
+Until the published date passes:
+
+- The maintenance is hidden from the status page and from public reads of the [API](/api-reference/introduction) — for guests and read-only API tokens alike.
+- It stays fully visible and editable in the dashboard, over the [MCP server](/v3.x/guide/mcp), and to API tokens with the `schedules.manage` ability.
+- Any [subscriber notifications](/v3.x/guide/subscribers) are deferred until the maintenance is published.
+
+This is independent of **Scheduled At**, which controls when the maintenance window itself begins. Leave **Published At**
+empty to publish the maintenance immediately.
+
+<Note>
+    Subscriber notifications for published maintenance are dispatched by the scheduled `cachet:publish-scheduled`
+    command, so make sure Cachet's [scheduler](/v3.x/installation) is running.
+</Note>
+
 ## Schedule updates
 
 You may need to provide an update on scheduled maintenance, for example if the maintenance is taking longer than expected, or