frontpage-host 0.3.15 → 0.3.16

package/AGENTS.md

@@ -282,6 +282,8 @@ AI Support Agent team guidance: administrators may set `guidanceEmail` through t
 
 ## Emails workspace workflows
 
+Campaign timing uses the existing `mail save --file` and `mail campaign preview|send|get` commands. Read [MAIL.md, Campaign scheduling](./MAIL.md#campaign-scheduling) before using it. Save document.scheduledAt as a future ISO timestamp with an explicit timezone, null for Send now, or omit to retain it. Saving never confirms sending; overdue drafts remain drafts. Read settings for the business timezone. Review the post-save content timestamp, exact audience, eligible count and saved schedule before campaign send with a stable requestKey. Confirmed groups/filters resolve once, and normal delivery restrictions remain. The owner agent uses save_mail_editor then manage_people area:campaign; MCP uses save_mail_editor and campaign.preview/send/get. Direct saved-email sends cannot bypass a dated campaign. Reuse exact requests after uncertain responses.
+
 See [MAIL.md](./MAIL.md) for the complete save contract, reusable people picker directory, saved campaign recipients, Off-series enrollment and resume timing, all sender settings/null resets, suppression rules, Sent queries and details, and retry-safe examples. `frontpage mail save --file save.json` saves template and pending series together; it never sends. New series default On; existing series retain their saved state. Save email steps before enrolling anyone. Check the returned series status before attaching it to a rule; an Off series holds enrollment until turned On. `frontpage mail people` reads the same site-scoped directory as the workspace. Use `frontpage help mail --json` for current commands and flags. No new CLI binary, API namespace or migration command is required. Hosted guides and article help must be updated through the Frontpage CLI.
 
 Rule placement: read a rule revision, then use `people workspace rules.place` with `id`, `owner` and `expectedRevision`. This only organizes the rule; it does not change its trigger or execution. New UI rules/attachments save paused. Generic attachment calls still need explicit `enabled:false` for paused creation. Saved optional conditions and exact duration minutes remain supported through CLI and agent calls.

package/MAIL.md

@@ -100,6 +100,89 @@ Include `audience` with a one_off document in the same `mail save` request. Supp
 
 For an audience-only change, the existing `mail campaign audience --id DOCUMENT_ID --file audience.json` remains supported. Its JSON is `{"audience":{"personIds":["PERSON_ID"]}}`, or `{"audience":null}` to clear. Saved selection is intent; final send review resolves groups and filters again, checks permission and delivery restrictions, and freezes the actual recipients and content. Started campaigns cannot be edited or sent twice with a new key. Read `PEOPLE.md` for preview/send review and stable send keys.
 
+## Campaign scheduling
+
+The workspace, CLI, owner agent and MCP use the same saved campaign and confirmation service. Send now is the default. Saving a date never confirms sending: a draft stays a draft even after that date passes. Only an explicit campaign confirmation makes it eligible for the worker. The worker selects confirmed (`pending`) campaigns whose scheduled time has arrived, or whose scheduled time is null. Its existing minute pass and delivery checks can delay sending; the selected time is the earliest send time, not a delivery guarantee.
+
+| Action | CLI | Owner agent | MCP |
+| --- | --- | --- | --- |
+| Read content | `mail email get ID --json` | `get_mail_email` | `frontpage_mail_read`, operation `get_mail_email` |
+| Read timezone | `mail settings get --json` | `set_mail_settings({})` (read only) | `frontpage_mail_read`, operation `get_mail_settings` |
+| Save draft, audience and timing | `mail save --file draft.json` | `save_mail_editor` | `frontpage_mail_write`, operation `save_mail_editor` |
+| Review audience | `mail campaign preview --file audience.json` | `manage_people`, area `campaign`, operation `preview` | `frontpage_mail_read`, operation `campaign.preview` |
+| Confirm sending or scheduling | `mail campaign send --id ID --file review.json --request-key KEY` | `manage_people`, area `campaign`, operation `send` | `frontpage_mail_write`, operation `campaign.send` |
+| Read saved audience, timing and status | `mail campaign get --id ID --json` | `manage_people`, area `campaign`, operation `get` | `frontpage_mail_read`, operation `campaign.get` |
+
+Use `--site YOUR_SITE --json` with each CLI command. Agent calls bind the current site; never supply a siteId. MCP calls take `slug`, `operation` and `payload`, with the same fields inside payload. Existing role, plan, consent and delivery checks apply.
+
+### Save a schedule without sending
+
+Read the current campaign and `mail settings get` first. Convert the owner's chosen local date and time using the saved IANA timezone. `document.scheduledAt` accepts a future ISO timestamp with `Z` or an explicit offset. Do not guess an offset or silently shift a time that does not exist during daylight-saving changes. Ask for clarification if a repeated local time is ambiguous.
+
+- A timestamp selects Schedule for later.
+- `null` selects Send now and clears the saved date. It still does not send.
+- Omitting the field preserves existing timing.
+- Templates and series do not accept this field.
+
+Example `draft.json` for an existing campaign; replace IDs, timestamps, content and audience with the current reviewed values. Omit id and expectedUpdatedAt when creating a new campaign. Choose a future date for the actual request.
+
+```json
+{
+  "requestKey": "UNIQUE_SAVE_KEY",
+  "document": {
+    "id": "CAMPAIGN_DOCUMENT_ID",
+    "expectedUpdatedAt": "EXACT_CURRENT_DOCUMENT_TIMESTAMP",
+    "kind": "one_off",
+    "name": "November update",
+    "subject": "Your November update",
+    "preheader": "News from our team.",
+    "blocks": [{"type":"paragraph","text":"Here is our latest news."}],
+    "scheduledAt": "2030-11-15T09:00:00-06:00"
+  },
+  "audience": {"personIds":["PERSON_ID"]}
+}
+```
+
+```sh
+frontpage mail save --file draft.json --site YOUR_SITE --json
+frontpage mail email get CAMPAIGN_DOCUMENT_ID --site YOUR_SITE --json
+frontpage mail campaign get --id CAMPAIGN_DOCUMENT_ID --site YOUR_SITE --json
+frontpage mail campaign preview --file audience.json --site YOUR_SITE --json
+```
+
+`audience.json` contains `{"audience":{"personIds":["PERSON_ID"]}}`. Supported choices also include `groupIds`, `stageIds`, `filters`, and `addresses`. The UI's Choose people option uses personIds; List individual email addresses uses addresses. Read `campaign get` to reuse a saved selection. When changing audience sources, send only the new source rather than merging the old selection. Use `audience:null` in `mail save` to clear it. Clearing or replacing an audience does not clear the saved schedule. Explicit addresses do not create People records or grant email permission.
+
+### Review and confirm
+
+Show the owner the content, eligible recipient count, and send date/time in the business timezone before confirmation. Fetch current content and campaign state after saving, and preview the exact audience. The confirmation file `review.json` carries those reviewed values:
+
+```json
+{
+  "review": {
+    "audience": {"personIds":["PERSON_ID"]},
+    "eligible": 1,
+    "documentUpdatedAt": "EXACT_POST_SAVE_DOCUMENT_TIMESTAMP",
+    "scheduledAt": "2030-11-15T15:00:00.000Z"
+  }
+}
+```
+
+```sh
+# This is the confirmation: it authorizes sending when due.
+frontpage mail campaign send --id CAMPAIGN_DOCUMENT_ID --file review.json --request-key UNIQUE_SEND_KEY --site YOUR_SITE --json
+frontpage mail campaign get --id CAMPAIGN_DOCUMENT_ID --site YOUR_SITE --json
+```
+
+Copy the canonical UTC scheduledAt from the saved response into review, or null for Send now. Use the exact post-save document timestamp and preview's eligible count; never use a timestamp from before an audience save. The service rejects a changed reviewed audience, count, content timestamp or scheduled time. A past date needs a new future date or Send now before confirmation. Existing older callers without review fields remain supported; agents should always supply the complete review.
+
+Confirmation freezes the eligible recipients and content. Groups and filters resolve at confirmation, not at the future send time. Permission, opt-out and delivery checks still apply before sending. A confirmed future campaign has stored status `pending` and scheduledAt; the UI labels that combination Scheduled. Drafts remain `draft` regardless of date. Queued, sent and delivered are different states; read campaign counts and the send ledger. Confirmed campaigns cannot be edited through this flow; cancellation and rescheduling are not added here.
+
+Keep the same requestKey and exact payload after an uncertain save or confirmation. Read back campaign state and retry the original request; never create a new send key to recover an uncertain result. A changed request needs a fresh review. The older `mail send email` / `send_mail_email` path sends immediately and cannot confirm a scheduled campaign; it returns a conflict for dated campaigns. Use campaign send instead. Test sends and dry runs do not confirm or start the campaign; existing test restrictions still apply.
+
+### Email capability release check
+
+For each changed Email capability, check its shared service, UI, public API, CLI help and examples, owner-agent schema/instructions, and MCP operation/docs. Add focused contract checks and test the real adapters. Run `node scripts/people/sync-agent-docs.mjs` after editing the packaged manuals and `node scripts/people/sync-agent-docs.mjs --check` before release. Publish hosted guides through the Frontpage CLI only, then verify the public page. Do not maintain a separate scheduling implementation or a second internal manual.
+
 ## People directory and enrollment
 
 ```bash

package/PEOPLE.md

@@ -577,6 +577,10 @@ frontpage mail campaign get --id DRAFT_ID --site YOUR_SITE --json
 
 Preview reports matched, eligible, no-email, suppressed, and permission-missing counts and sends nothing. Sending freezes content and eligible recipients, deduplicates email addresses, and uses the existing paced email queue. Reuse the send request key after a lost response. Check `campaign get` for queued, sent, pending, failed, and skipped work; queued does not mean delivered.
 
+Campaigns can also schedule a future send through `mail save` with `document.scheduledAt`. A date on a draft never sends it. After reviewing content, audience and time, `mail campaign send` confirms the saved schedule; the existing worker waits until due. Send now uses scheduledAt:null. `campaign get` returns stored status and scheduledAt; pending plus a future time displays Scheduled in the UI. Groups and filters resolve when confirmed. Read [MAIL.md, Campaign scheduling](./MAIL.md#campaign-scheduling) for complete save, review, retry, agent and MCP examples. Direct `mail send email` is for immediate unscheduled sends and cannot bypass a saved schedule.
+
+For the owner agent, call `set_mail_settings({})` to read the business timezone, then `save_mail_editor` with a one_off document and future ISO scheduledAt including Z or an explicit offset. Omission preserves timing; null clears it. Read `get_mail_email` after saving and `manage_people` with area:campaign, operation:get for saved timing/audience, then operation:preview for the exact audience and eligible count. Show the owner the content, recipients and local send time. On explicit confirmation, call `manage_people` with area:campaign, operation:send, payload:{documentId,requestKey,review:{audience,eligible,documentUpdatedAt,scheduledAt}}. Use the post-save document timestamp, preview count and canonical saved UTC time. These values must still match; a changed review needs a fresh read and approval. Keep the original requestKey and payload after an uncertain result and read back state before retrying. Never use direct send_mail_email to bypass timing. MCP uses `frontpage_mail_write` operation:save_mail_editor and campaign.send, with campaign.get/preview through `frontpage_mail_read`. A confirmed campaign cannot be edited or rescheduled in this flow.
+
 ## CLI, API, and agent reference
 
 The editor, public API, CLI, and site agent call the same application service. Every operation below is available without opening the UI.

package/dist/registry.js

@@ -591,6 +591,8 @@ export const COMMANDS = [
             "frontpage mail series steps set <id> --file steps.json",
             "frontpage mail template history <id> --limit 20 --json",
             "frontpage mail template history-get <id> --history-id <saved-copy-id> --json",
+            "frontpage mail save --file scheduled-draft.json --site YOUR_SITE --json",
+            "frontpage mail campaign send --id DRAFT_ID --file review.json --request-key SEND_KEY --site YOUR_SITE --json",
             "frontpage mail suppress add --email bounce@example.com",
         ],
         flags: [
@@ -600,6 +602,7 @@ export const COMMANDS = [
             "sends list --q --status --type campaign|series|confirmation|template|test|inline --page 1 --limit 20.",
             "Series status active means On; paused/draft mean Off. Enrollment while Off waits at step 1, without sending. Existing people resume their next unsent step.",
             "campaign preview|audience|send|get. --id DRAFT_ID, --file audience.json ({audience:{groupIds|stageIds|personIds|filters}}). send requires --request-key; reuse it after a network error. Templates/series are for automation; campaigns have separate drafts. See PEOPLE.md.",
+            "Schedule campaigns through save document.scheduledAt (future ISO time with timezone); null means Send now, omission preserves timing. A dated draft never sends until campaign send confirms it. Supply review:{audience,eligible,documentUpdatedAt,scheduledAt} from fresh saved reads/preview. campaign get returns status and scheduledAt; pending plus a future date means Scheduled. Direct send email cannot bypass saved timing. See MAIL.md, Campaign scheduling.",
             "template history <id> pages saved copies with --limit (20 by default, max 100) and --cursor. history-get <id> --history-id reads full content. Both reads follow the plan Rewind window, plus Latest at any age; older copies stay stored. Lists report windowDays, unlimited, canUpgrade and moreBeyondWindow. Use template set with the stable template ID to save edited content as latest; past copies stay unchanged. Read template get before editing. History begins with content retained when history shipped, not lost earlier edits.",
             "email list is unsent drafts only. Sent one-offs are mail sends list",
             "send --file is an inline one-off (no saved document)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontpage-host",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {