frontpage-host 0.1.28 → 0.1.29

package/AGENTS.md

@@ -256,3 +256,8 @@ frontpage doctor --json
 ## People groups, stages, rules, and imports
 
 Use `frontpage people overview`, `groups`, `stages`, `membership`, `rules`, `attachments`, `import`, and `company`. Use `frontpage mail campaign` for one-off group/stage/list audiences in Emails. Every editor action is available through these commands or `frontpage people workspace OPERATION --file payload.json`. Full operations and examples: [PEOPLE.md](./PEOPLE.md); public guide: https://frontpage.host/developers/people. Automated emails select a saved template or series. Campaigns use their own drafts.
+
+
+## Customer Inbox
+
+Internal, allowlisted sites only. Use `frontpage customer-inbox get|put|post RESOURCE`, stable write keys and current versions. Full guide: [CUSTOMER-INBOX.md](./CUSTOMER-INBOX.md). `export CONVERSATION_ID --out FILE` writes authorized paginated history and file metadata; `download FILE_ID --out FILE` downloads through a file grant. Outputs never overwrite existing files. `frontpage usage` reports shared site credits, mail and storage. Human owners may handle conversations; website agents use `manage_customer_inbox` for setup/settings/widget/internal knowledge only, never a human CLI key to read or join customer threads.

package/CUSTOMER-INBOX.md

@@ -0,0 +1,217 @@
+# Customer Inbox
+
+Customer Inbox uses the site's existing AI credits and storage allowance. It is available on internal plans and approved pilot sites. The support agent uses fixed GPT-6 Luna and bills AI usage at 10× raw provider cost. Human handling does not call a model for each message.
+
+Run `frontpage help customer-inbox`. Use the site's normal CLI key:
+
+```sh
+frontpage customer-inbox get status --site my-site
+frontpage customer-inbox get settings --site my-site
+frontpage customer-inbox put settings --file ./settings.json --request-key settings_revision_1 --site my-site
+```
+
+Reads use `get`. Writes use `put` or `post`, a UTF-8 JSON object file, and an 8–128 character request key. Reuse the same key and body after a failed or lost response. Changed bodies need new keys. The service rejects a key reused for a different request. Read current versions before changing records.
+
+## Setup and settings
+
+| Resource | Method | JSON body |
+| --- | --- | --- |
+| `status` | GET | None |
+| `activation` | PUT | `{"enabled":true}`; admin only |
+| `address` | GET | Returns the current address, domain and policy version |
+| `address` | PUT | `{"alias":"acme","policyVersion":"2026-10-13.1"}`; admin only |
+| `address` | POST | `{"retire":true}`; admin only |
+| `settings` | GET | Returns `version`, `value`, fixed model and multiplier |
+| `settings` | PUT | `{"expectedVersion":0,"value":{"instructions":"Ask me if unsure."}}` |
+
+Setup binds private guidance to the verified owner who requested it. That identity comes from Core, never model/customer fields. The agent manages new conversations by default after setup; the platform's rollout switches remain off until pilot verification passes. Set `value.enabled:false` for manual handling. Settings changes cancel stale automatic jobs and queued automatic sends.
+
+Settings allow `enabled`, `instructions`, `tools`, `maxSteps` (1–12), `maxOutputTokens` (256–2400), and `maxInputBytes` (4000–64000). Supported tools: `knowledge_read`, `knowledge_update`, `customer_read`, `customer_update`, `notes_read`, `note_add`, `ask_owner`, `reply_customer`, `wait`, `finish`. Keep `wait` and `finish` enabled. Defaults: 8 steps, 1200 output tokens per call, 32000 bytes of public text. Model, billing multiplier and recipients are not caller-selectable fields. The worker also enforces platform concurrency, deadlines and input limits.
+
+Aliases use 3–48 ASCII letters, numbers and single hyphens. The service normalizes case and checks collisions in one transaction. Reserved platform names and routing namespaces cannot be claimed. Retired addresses remain reserved; they never move to another site.
+
+## Internal knowledge and approved sources
+
+| Resource | Method | JSON body |
+| --- | --- | --- |
+| `knowledge` | GET | Recent notes; optional `?q=search` |
+| `knowledge/<id>` | GET | One full note |
+| `knowledge/<id>/history` | GET | Immutable revisions for that note |
+| `knowledge` | PUT | `{"title":"Evening visits","body":"Ask the owner before promising an evening visit.","expectedVersion":0,"reason":"Owner policy"}` |
+| `knowledge/<id>` | PUT | Current title/body, `expectedVersion`, `reason`, optional `locked` or `restoreVersion` |
+| `sources` | GET | Approved source records |
+| `sources` | PUT | `{"url":"https://example.com/help","enabled":true,"expectedVersion":0}`; fetches public text |
+
+Supply `body` on a source write to save an owner-approved excerpt instead of fetching. Published sources refresh when the agent reads a source older than 24 hours. The fetcher reuses Core's DNS-pinned public HTTP infrastructure, rejects private addresses, checks redirects and bounds content. Sources over 16000 text characters require an owner-approved excerpt. No scripts run. A source version/digest fences knowledge updates against a changed source.
+
+Knowledge search uses bounded literal keywords from natural-language queries and ranks notes by matched terms. Read the full matching note before updating it; update its current ID/version instead of creating a conflicting duplicate.
+
+Lock a knowledge note with `locked:true`. The support agent cannot change locked notes or locks. Restore an older note with `restoreVersion`; the service creates a new revision and preserves the old history. The agent can change only internal knowledge, using verified owner guidance or a current approved source. It cannot edit public pages or articles.
+
+## Human conversation handling
+
+| Resource | Method | JSON body |
+| --- | --- | --- |
+| `conversations` | GET | Paginated list; `?limit=50&after=<id>` |
+| `conversations/<id>` | GET | Thread and latest public message |
+| `conversations/<id>/messages` | GET | `?after=0&limit=50&audience=all`; viewers get public history only |
+| `conversations/<id>/routing` | GET | Current handler/version, People link and delivery states |
+| `conversations/<id>/reply` | POST | `{"text":"Tuesday at 6:30 works. Keep staffing private.","handlerVersion":0,"privateGuidance":true}` |
+| `conversations/<id>/control` | POST | `{"action":"takeover","handlerVersion":0}` or `{"action":"return","handlerVersion":1}` |
+| `conversations/<id>/reply` | POST | `{"text":"Your quote is ready.","handlerVersion":1}`; requires current owner control |
+| `files?messageId=<id>` | GET | Bound message files; editor/admin only |
+| `files/<id>` | GET | Short-lived download grant; editor/admin only |
+
+Private guidance stays in the same internal thread. The agent asks by a private email and stores its question in the history. Replying by email or UI gives context and leaves the agent responsible for the customer. The agent uses that context to answer and can update unlocked internal knowledge.
+
+Email replies route through opaque, recipient-bound Reply-To addresses linked to the site, conversation, purpose, owner and handler version. Subjects and message text never choose a customer thread. The service checks current owner membership and sender authentication before accepting private owner mail. To take over by email, reply only `Take over this conversation`. The owner receives the customer-visible history and replies through Inbox. If history exceeds the email limit, the notification links to the full paginated history/export; it never claims a shortened transcript is complete. To return control, reply only `Agent, take it from here`. Mixed or unclear handoff text stays private for review. Customer and owner addresses are never added to a shared CC thread by Inbox.
+
+Manual customer/owner exchanges use ordinary routing code. No support inference runs for every manual message. Returning control checks only eligible unanswered input and suppresses stale automatic sends.
+
+Set `enabled:false` in settings to use manual handling for new conversations. The service binds that relay to the configured verified owner. Existing agent threads switch to manual handling on the next customer message or public owner reply. Re-enable the agent before returning a thread to it. Private guidance alone always stays private and never transfers control.
+
+Set `guidanceToMe:true` in a versioned settings update to bind the signed current owner's verified address. Arbitrary recipient addresses and user IDs remain forbidden. The service saves only the resolved owner identity, not this setup flag.
+
+## Security review and recovery
+
+| Resource | Method | JSON body |
+| --- | --- | --- |
+| `blocks` | GET | Site-scoped block evidence references; human editor/admin only |
+| `blocks/<id>/unblock` | POST | `{"version":1}` |
+| `jobs` | GET | Job state/reason and current `updatedAt` |
+| `jobs/<id>/resume` | POST | `{"updatedAt":"<current ISO time>"}` for recoverable budget, receipt, rate or service pauses |
+| `receipts` | GET | Held inbound mail; admin only |
+| `receipts/<id>` | POST | `{}` queues a held capture retry; admin/pilot only |
+
+Only a validated clear attack can create an automatic site-scoped block. Authenticated customer mail binds a verified email identity; unverified mail stays thread-scoped. Blocks never ban a People contact across sites or a shared IP. Unblock preserves evidence and does not replay the attack. Uncertain, malformed, refused or unavailable screening pauses the agent and leaves human handling available. Known blocks and rate/size checks stop work before another paid call.
+
+The fixed policy requires allow probability at least 0.90 and confidence at least 0.80, with no attack category. Automatic blocking requires malicious probability and confidence at least 0.98 and an attack category. Other results pause for human review; a review does not label the customer malicious. These are platform controls, not customer settings. Review email notices deduplicate per conversation and reason group per hour. Saved receipt retries wait at least 30 seconds so one failed receipt cannot monopolize recovery.
+
+Receipt recovery resubmits saved provider usage to the existing ledger. It never repeats inference. An interrupted request with unknown completion requires review. Resume cannot bypass screening, replay a blocked attack, or pretend unknown usage is zero. Exact input/output/cache/reasoning counts stay unchanged; the ledger records raw cost, fixed multiplier, customer debit, job/call/conversation references and immutable prices.
+
+## Website-agent management boundary
+
+The website agent uses `manage_customer_inbox` and `get_customer_inbox_docs`, with a signed manager principal bound to the owner run. It manages settings, tools, aliases and internal knowledge. It cannot read live threads or files, send messages, provide private guidance, take over/return, or review customer block evidence. Server checks enforce this even through indirect paths. Never give the website agent a human CLI/API key. Its manager tool uses no human keychain credential.
+
+The developer guide lives at `https://frontpage.host/developers/customer-inbox`. Changes to that site use the Frontpage CLI pull/push/deploy/publish process.
+
+## Owner workspace and widget
+
+Open `/workspace/sites/<siteId>/customer-inbox` on an approved internal site. The workspace uses the same versioned service operations as the CLI. Conversation rows show the latest public message. Customer messages, agent replies, owner replies, private guidance, notes and handling changes have distinct labels. Private guidance stays in the thread and does not transfer ownership.
+
+Use `frontpage customer-inbox get widget --site my-site` as a human admin to get the script URL, site ID and server-side app identity key. Install the returned script through the normal Frontpage CLI file workflow or your app's template:
+
+```html
+<script defer src="https://app.frontpage.host/customer-inbox/widget.js" data-site="SITE_UUID"></script>
+```
+
+The current scaffold and gateway already allow this HTTPS script and its requests. Installation uses their existing script support; it needs no gateway change, scaffold upgrade or fleet rebuild. The widget stays separate from the site bundle. It appears only when the service accepts that site's activation, rollout gates and approved origin.
+
+Update settings using the current `expectedVersion`:
+
+```json
+{
+  "expectedVersion": 4,
+  "value": {
+    "widget": {
+      "enabled": true,
+      "title": "Message our team",
+      "greeting": "How can we help?",
+      "color": "#7254d6",
+      "requireName": true,
+      "requireEmail": true,
+      "origins": ["https://my-site.frontpage.host", "https://app.example.com"]
+    },
+    "ownerCopies": false,
+    "helpRules": {
+      "humanRequest": true,
+      "missingAnswer": true,
+      "frustration": true,
+      "repeatedFailure": true
+    }
+  }
+}
+```
+
+Use exact HTTPS origins without paths or credentials. This controls cross-origin browser access, not owner permissions. Required intake fields collect details; they do not prove email ownership. The customer must confirm the emailed link before email continuation or authenticated People access. Confirmation rotates the visitor credential. Recovery uses a new email proof and returns no history based on a typed address alone.
+
+The agent reads help rules in its support prompt and uses `ask_owner`. Work caps remain server-enforced. Owner copies are private emails of future agent replies. Replying gives private guidance unless the owner explicitly requests takeover. Neither copies nor guidance put owner and customer on a shared CC thread.
+
+### Signed app identity
+
+Keep the `identityKey` returned by `widget` on your app server. Never include it in HTML, browser storage or a client bundle. Sign a short-lived assertion after authenticating your app user:
+
+```js
+import { createHmac } from "node:crypto";
+const now = Math.floor(Date.now() / 1000);
+const claims = {
+  siteId: process.env.INBOX_SITE_ID,
+  origin: "https://app.example.com",
+  subject: authenticatedUser.id,
+  email: authenticatedUser.email,
+  name: authenticatedUser.name,
+  iat: now,
+  exp: now + 120
+};
+const encoded = Buffer.from(JSON.stringify(claims)).toString("base64url");
+const identity = encoded + "." + createHmac("sha256", process.env.INBOX_IDENTITY_KEY)
+  .update(encoded).digest("hex");
+```
+
+The service verifies the signature, site, origin and expiry. Assertions can last at most five minutes. They grant customer identity only, never owner or manager authority. Every app-session request must include the current signed identity matching that session's subject and email. Put a server-rendered assertion in `data-identity`, or preferably provide `data-identity-url="/api/support-identity"`. That same-origin HTTPS endpoint authenticates the current app user and returns `{"identity":"<signed assertion>"}`. The widget refreshes it; after logout or account changes, old app sessions cannot be read without the matching identity. Anonymous widgets need no assertion. Each approved origin has its own visitor session; email continues the bound conversation.
+
+## Conversation state, exports and shared usage
+
+| Resource | Method | Body or behavior |
+| --- | --- | --- |
+| `conversations?state=active` | GET | Open threads; also `closed`, `trash` or `all` |
+| `conversations/<id>/messages?latest=true&limit=50&audience=all` | GET | Latest page in message order |
+| `conversations/<id>/messages?before=<sequence>&limit=50&audience=all` | GET | Earlier page; do not combine with `after` or `latest` |
+| `conversations/<id>/state` | POST | `{"action":"close","expectedVersion":0}`; actions: `close`, `reopen`, `trash`, `restore`, `read` |
+| `conversations/<id>/state` | POST | Mark read with current state version and `"sequence":42` |
+| `conversations/<id>/revoke-sessions` | POST | `{}`; revoke existing visitor credentials |
+
+Trash retains history and file references. Restore reopens the thread; it does not erase prior handling decisions. State writes reject stale versions. Closing cancels queued sends and refuses unresolved provider outcomes. New customer input reopens a closed thread; trashed threads require owner restoration. Visitor revocation also disables recovery of that session.
+
+Export the full authorized history and file manifest, one JSON record per line:
+
+```sh
+frontpage customer-inbox export CONVERSATION_UUID --out ./conversation.jsonl --site my-site
+frontpage customer-inbox download FILE_UUID --out ./attachment.png --site my-site
+frontpage usage --site my-site --json
+```
+
+Export uses paginated reads rather than loading all messages into memory. Download uses an authorized file grant. Both commands refuse to overwrite an existing output file. Full private-history export and file access require human editor/admin authority. Viewers can read public history through the normal message resource.
+
+Inbox sends count in the site's existing email allowance. Provider-accepted send receipts settle that usage once, including private owner notifications and copies. AI calls debit the site's existing credit ledger at 10× cost, with token counts unchanged. Storage uses the existing Blob scanner and counts actual attachments, originals and previews; conversation text adds no separate meter.
+
+## File custody and cleanup
+
+Email capture keeps the original MIME message, attachments and provider receipt. Email and chat image uploads keep the original file and a smaller agent preview. Repeated upload/message receipts retain the same file/message IDs. Validated raster customer images up to 12 megapixels use the existing public bucket. Larger or undecodable files remain downloadable and require human review. Other files and private mail originals use authenticated downloads over encrypted bytes in that same bucket. No Blob firewall changes or separate bucket are part of this release.
+
+The existing backup process enumerates the whole bucket. The existing reaper scans Inbox files in bounded pages and asks Inbox for exact retained references; it does not read message bodies. Unknown reference results protect Inbox files while legacy cleanup continues. Live history, Trash, capture holds and original/preview links retain their files. The existing archive/restore/purge coordinator claims a file in Inbox before changing bytes. A claim blocks new links and remains held after an unknown outcome. Accepted email custody, message links, Trash and capture holds protect files; abandoned chat uploads can follow the existing grace/archive rules. Unknown file records stay protected. Site finalization freezes Inbox writes before moving its bytes through the same archive process. Broader shared-reaper performance work remains a later phase.
+
+
+On app logout or account change, call `window.dispatchEvent(new Event("frontpage-inbox:reset"))`. This clears the displayed history, stored chat credential and pending input. The next request fetches a fresh assertion from `data-identity-url`; authenticated app sessions require the same current app identity on every request. Do not use a long-lived static assertion for an app with account switching. Verification returns to the same origin and the stored page path. Query strings and arbitrary redirect URLs are not accepted.
+
+`jobs/<id>` reads one human-visible recovery state. Retry only the documented recoverable pauses using its current `updatedAt`; invalid screening and unknown sends require human review. An unknown shared-media operation keeps its `claimId`, `claimAction` and `lifecycleVersion`. Operators verify live/archive byte hashes and the existing archive row before acknowledging the matching service-only `/media-finish` operation. Never clear a claim solely because time passed. These endpoints accept only the `inbox-media` service actor; owner keys and website managers cannot submit them.
+
+
+## Support agent tool contract
+
+The support agent has its own system prompt plus the versioned private business instructions. Tool calls stay in Inbox's tenant, conversation, handler, configuration and job context. All ten tools start enabled; `wait` and `finish` cannot be removed. A disabled tool fails at the server.
+
+| Tool | Inputs | Effect and limits |
+| --- | --- | --- |
+| `knowledge_read` | `query`, `id` or `sourceId` | Search internal notes or read complete approved evidence. |
+| `knowledge_update` | Optional `id`; `title`, `body`, `expectedVersion`, `reason`, `evidenceKind`, `evidenceId`; source `evidenceVersion` | Update unlocked internal facts from verified guidance in this thread or an approved source revision. One-off guidance stays in the conversation. No public editing. |
+| `customer_read` | None | Read only this thread's verified People contact. |
+| `customer_update` | `name`/`phone`, `evidenceMessageId` | Enrich from an explicit customer statement; cannot change identity or permission. |
+| `notes_read` | None | Read factual People notes for the bound contact. |
+| `note_add` | `text` | Save a private factual action note in People, with an idempotent receipt. Do not store hidden reasoning. |
+| `ask_owner` | `question` | Save the private question in the thread, email the verified configured owner and pause. Guidance does not take over. |
+| `reply_customer` | `text` | Save a public answer and queue email to the bound verified customer when available. Never choose recipients. |
+| `wait` | `reason` | Pause safely without sending. |
+| `finish` | None | Complete this bounded job. |
+
+Decisions screens malicious input only. It never chooses customer recipients, business answers, tools, owner handling or knowledge changes. Shared inference utilities provide the existing same-model credential/transport fallback; no expensive model substitution or customer model picker is added.

package/PEOPLE.md

@@ -411,6 +411,23 @@ For a reviewed cohort, submit at most 25 people in each bounded batch. Each row
 
 Run the same `person permission --file reviewed-batch.json` command. Read every row in `results`: domain conflicts include `error` and `status`, while successful rows include `emailPermission` and `duplicate`. The batch can partly succeed; receipts make a retry safe. Malformed batch input fails before any permission writes. Infrastructure errors can leave completed receipts, so retry the exact batch rather than inventing new keys. This capability works through the public API and `manage_people` too; it has no company-only endpoint.
 
+## Safe sync through public customer commands
+
+Integrations read their own sources and write through the same CLI/API/agent operations as owners. No product database write credential is needed.
+
+- `person.lookup` takes a valid `email` and/or `phone`, includes hidden matches, and refuses identities that point to different people. It never changes permission or unhides someone.
+- `person.update` takes `personId`, a `patch` and optional `expected` contact values. `expected` supports exact name/email/phone values, including null. A changed value or hidden contact returns a conflict; it does not overwrite the owner's edit. Use `people workspace person.update --data` for this conditional operation.
+- `notes.add` takes `personId`, `body`, optional `requestKey` (1–120 characters), and optional `historical` boolean. Reuse the key for the exact same note after a lost response. A changed person/body/history flag returns a conflict. A retry never restores a deleted note. Historical notes skip automation and record their processed receipt immediately.
+- `membership.add` accepts optional `historical:true` to import a membership without replaying rules. Ordinary additions keep normal automation. Preserve an owner's removed membership rather than adding it again on every sync.
+
+```sh
+frontpage people workspace person.lookup --data '{"email":"alex@example.com"}' --site YOUR_SITE --json
+frontpage people workspace person.update --data '{"personId":"PERSON_ID","patch":{"phone":"+12025550100"},"expected":{"phone":null}}' --site YOUR_SITE --json
+frontpage people workspace notes.add --data '{"personId":"PERSON_ID","body":"Verified billing context","requestKey":"NOTE_UUID","historical":true}' --site YOUR_SITE --json
+```
+
+Use a saved CSV import for a new historical cohort. Its list-wide permission choice applies only to new contacts; row values take priority and existing decisions remain saved. Check the real import status before writing notes or starting delivery. Source account or billing facts never imply marketing permission. Preserve hidden state and review identity conflicts rather than merging contacts.
+
 ## Import a customer list from CSV
 
 CSV imports accept up to 5 MB and 10,000 contact rows. Quoted commas, quoted newlines, UTF-8 BOM, and CRLF are supported. Larger lists need separate files; the UI does not render an unbounded list of failures.
@@ -508,18 +525,6 @@ 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.
 
-## Frontpage account sync
-
-This admin-only feature adds Frontpage’s own account holders to the `landing` People workspace and keeps later signups in sync. It is not available to ordinary businesses. Businesses import their customer lists with CSV.
-
-```
-frontpage people company get --site landing --json
-frontpage people company set --enabled true --site landing --json
-frontpage people company set --enabled false --site landing --json
-```
-
-Sync uses saved batches and Frontpage user IDs to avoid duplicates. The backfill does not fire rules or grant email permission. Later signups can trigger group entry rules, subject to normal eligibility. Sync preserves owner edits. Pausing it leaves existing contacts saved. Supply an existing `groupId` through `--data` if you want a particular sync group.
-
 ## 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.
@@ -612,8 +617,6 @@ The agent can create and edit saved templates and series with the existing Email
 | import.start                               | csv, mapping?, groupIds?, requestKey                                | Start a saved import.                                                                    |
 | import.get                                 | id                                                                  | Read the import cursor, outcomes, and errors.                                            |
 | import.retry                               | id                                                                  | Retry failed rows after correcting saved identity conflicts.                             |
-| company.get                                | —                                                                   | Read the admin-only Frontpage account sync.                                              |
-| company.set                                | enabled, groupId?                                                   | Start or pause that sync in landing; platform admin only.                                |
 
 ## Limits, timing, and recovery
 
@@ -628,3 +631,20 @@ The agent can create and edit saved templates and series with the existing Email
 **Keep scope clear.**
 
 People does not replace the raw Inbox, Store orders, or the email send ledger. It combines the contact’s history and organization. Those source tools and their existing CLI commands remain available.
+
+## Manual saved emails from People
+
+Templates store reusable content; series store ordered templates and delays. Neither definition stores a customer audience. Their existing API/CLI sends and rule callers remain supported. In People, use **Email → Use a template** to create an independent campaign draft with the current audience. Review the draft before sending; editing it never changes its source template. A template's **Create campaign** shortcut copies saved content, then asks for a campaign audience.
+
+The shared workspace operations are:
+
+```
+frontpage people workspace template.campaign --site YOUR_SITE --data '{"templateId":"TEMPLATE_ID","requestKey":"YOUR_STABLE_KEY","audience":{"personIds":["PERSON_ID"]}}' --json
+frontpage people workspace series.preview --site YOUR_SITE --data '{"seriesId":"SERIES_ID","personIds":["PERSON_ID"]}' --json
+```
+
+To enrol, copy each returned batch's `personIds` and `reviewToken` into `series.enrol`, adding `seriesId` and a unique stable `requestKey`. Preview returns batches of five; the service accepts at most 25 per request. Reuse the original payload and key after a lost response. Results distinguish enrolled, already enrolled, skipped and failed. A new preview uses new keys. Never enrol or send without the user's explicit instruction.
+
+Manual series starts use selected person IDs, an active series and the normal queue. Confirmation queues its first email; saved delays schedule later steps. The review lists permission exclusions and remaining allowance. It never activates a paused series or restarts an existing enrolment, including one bound to a person whose email changed. Delivery rechecks saved restrictions. Contact groups and permission stay unchanged.
+
+People supplies first-name and unsubscribe values. If content uses order, booking or other caller-only variables, edit the independent campaign or choose another series. Do not invent values or send empty required context.

package/dist/bin.js

@@ -26,6 +26,7 @@ import { runExtensions } from "./commands/extensions.js";
 import { runMedia } from "./commands/media.js";
 import { runImages } from "./commands/images.js";
 import { runInbox } from "./commands/inbox.js";
+import { runCustomerInbox } from "./commands/customer-inbox.js";
 import { runSeo } from "./commands/seo.js";
 import { runRedirects } from "./commands/redirects.js";
 import { runPeople } from "./commands/people.js";
@@ -117,6 +118,8 @@ async function main() {
             return runImages(args);
         case "inbox":
             return runInbox(args);
+        case "customer-inbox":
+            return runCustomerInbox(args);
         case "people":
             return runPeople(args);
         case "routines":

package/dist/commands/customer-inbox.d.ts

@@ -0,0 +1,14 @@
+export declare function inboxCommand(args: string[]): {
+    method: string;
+    resource: string;
+    file: undefined;
+    key: undefined;
+    out: string;
+} | {
+    method: string;
+    resource: string;
+    file: string | undefined;
+    key: string | undefined;
+    out: undefined;
+};
+export declare function runCustomerInbox(args: string[]): Promise<number>;

package/dist/commands/customer-inbox.js

@@ -0,0 +1,157 @@
+import { readFile, open, link, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { resolveSlug } from "../site.js";
+import { takeFlag, assertNoUnknownFlags } from "../argv.js";
+import { getApiKey } from "../auth/keychain.js";
+import { apiBase, v1Get, httpErrorFromV1, CliHttpError, EXIT_AUTH, EXIT_USAGE, EXIT_OK, exitCodeForError, } from "../http/client.js";
+import { emitOk, emitErr, isJson } from "../runtime.js";
+const RESOURCE = /^(?:status|activation|address|widget|settings|knowledge(?:\/[0-9a-f-]+(?:\/history)?)?|sources|blocks(?:\/[0-9a-f-]+\/unblock)?|jobs(?:\/[0-9a-f-]+(?:\/resume)?)?|files(?:\/[0-9a-f-]+)?|receipts(?:\/[0-9a-f-]+)?|conversations(?:\/[0-9a-f-]+(?:\/(?:messages|routing|guidance|reply|control|state|revoke-sessions))?)?)(?:\?[^#]*)?$/;
+export function inboxCommand(args) {
+    const work = [...args], verb = work.shift(), resource = work.shift(), file = takeFlag(work, "--file"), key = takeFlag(work, "--request-key"), out = takeFlag(work, "--out");
+    assertNoUnknownFlags(work, "customer-inbox");
+    if (verb === "export" || verb === "download") {
+        if (work.length ||
+            !resource ||
+            !out ||
+            file ||
+            key ||
+            !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(resource))
+            throw new CliHttpError("Use customer-inbox export|download <id> --out <new-file>.", EXIT_USAGE, 400, "bad_request");
+        return {
+            method: verb.toUpperCase(),
+            resource,
+            file: undefined,
+            key: undefined,
+            out,
+        };
+    }
+    if (out ||
+        work.length ||
+        !verb ||
+        !["get", "put", "post"].includes(verb) ||
+        !resource ||
+        !RESOURCE.test(resource))
+        throw new CliHttpError("Usage: frontpage customer-inbox get|put|post <resource> [--file <json>] [--request-key <key>] [--site <slug>]", EXIT_USAGE, 400, "bad_request");
+    if (verb !== "get" && (!file || !key || !/^[A-Za-z0-9_-]{8,128}$/.test(key)))
+        throw new CliHttpError("Writes require --file and an 8–128 character --request-key. Reuse both on retries.", EXIT_USAGE, 400, "bad_request");
+    if (verb === "get" && (file || key))
+        throw new CliHttpError("Reads do not take --file or --request-key.", EXIT_USAGE, 400, "bad_request");
+    return { method: verb.toUpperCase(), resource, file, key, out: undefined };
+}
+export async function runCustomerInbox(args) {
+    try {
+        const { slug, rest } = await resolveSlug(args), operation = inboxCommand(rest), path = `/api/v1/sites/${encodeURIComponent(slug)}/customer-inbox/${operation.resource}`;
+        let result;
+        if (operation.method === "EXPORT" || operation.method === "DOWNLOAD") {
+            const target = operation.out, temp = target + ".inbox-" + randomUUID() + ".tmp", handle = await open(temp, "wx", 0o600);
+            let count = 0;
+            try {
+                const prefix = `/api/v1/sites/${encodeURIComponent(slug)}/customer-inbox`;
+                if (operation.method === "DOWNLOAD") {
+                    const record = await v1Get(`${prefix}/files/${operation.resource}`);
+                    const response = await fetch(record.data.downloadUrl, {
+                        redirect: "error",
+                        signal: AbortSignal.timeout(60000),
+                    });
+                    if (!response.ok || !response.body)
+                        throw new CliHttpError("Attachment download failed.", EXIT_USAGE, response.status, "download_failed");
+                    for await (const chunk of response.body) {
+                        count += chunk.byteLength;
+                        if (count > 25 * 1024 * 1024)
+                            throw new CliHttpError("Attachment exceeds 25 MB.", EXIT_USAGE, 413, "payload_too_large");
+                        await handle.writeFile(chunk);
+                    }
+                }
+                else {
+                    const conversation = await v1Get(`${prefix}/conversations/${operation.resource}`);
+                    await handle.writeFile(JSON.stringify({ type: "conversation", value: conversation.data }) +
+                        "\n");
+                    let cursor = 0;
+                    for (;;) {
+                        const page = await v1Get(`${prefix}/conversations/${operation.resource}/messages?after=${cursor}&limit=100&audience=all`);
+                        for (const message of page.data.messages) {
+                            const attachments = await v1Get(`${prefix}/files?messageId=${message.id}`);
+                            await handle.writeFile(JSON.stringify({
+                                type: "message",
+                                value: message,
+                                attachments: attachments.data,
+                            }) + "\n");
+                            count++;
+                        }
+                        if (page.data.nextCursor === null)
+                            break;
+                        if (page.data.nextCursor <= cursor)
+                            throw new Error("History cursor did not advance.");
+                        cursor = page.data.nextCursor;
+                    }
+                }
+                await handle.sync();
+                await handle.close();
+                await link(temp, target);
+                await unlink(temp);
+            }
+            catch (e) {
+                await handle.close().catch(() => { });
+                await unlink(temp).catch(() => { });
+                throw e;
+            }
+            result = {
+                path: target,
+                ...(operation.method === "EXPORT"
+                    ? { messages: count, format: "jsonl" }
+                    : { bytes: count }),
+            };
+            if (isJson())
+                emitOk("customer-inbox", result);
+            else
+                console.log(JSON.stringify(result, null, 2));
+            return EXIT_OK;
+        }
+        if (operation.method === "GET")
+            result = await v1Get(path, { timeoutMs: 20000 });
+        else {
+            const bytes = await readFile(operation.file);
+            if (bytes.length > 65536)
+                throw new CliHttpError("Inbox JSON exceeds 64 KiB.", EXIT_USAGE, 413, "payload_too_large");
+            let value;
+            try {
+                value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+            }
+            catch {
+                throw new CliHttpError("Use a valid UTF-8 JSON object.", EXIT_USAGE, 400, "bad_request");
+            }
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw new CliHttpError("Use a JSON object.", EXIT_USAGE, 400, "bad_request");
+            const token = await getApiKey();
+            if (!token)
+                throw new CliHttpError("Not logged in. Run: frontpage login", EXIT_AUTH, 401);
+            const response = await fetch(apiBase() + path, {
+                method: operation.method,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    "Idempotency-Key": operation.key,
+                },
+                body: JSON.stringify(value),
+                redirect: "error",
+                signal: AbortSignal.timeout(20000),
+            });
+            const body = (await response.json());
+            if (!response.ok)
+                throw httpErrorFromV1(response.status, body);
+            result = body;
+        }
+        if (isJson())
+            emitOk("customer-inbox", result);
+        else
+            console.log(JSON.stringify(result, null, 2));
+        return EXIT_OK;
+    }
+    catch (e) {
+        if (isJson())
+            emitErr("customer-inbox", e);
+        else
+            console.error(e instanceof Error ? e.message : "Inbox request failed.");
+        return exitCodeForError(e);
+    }
+}

package/dist/commands/people-workspace.js

@@ -10,7 +10,6 @@ const AREAS = [
     "import",
     "attachments",
     "person",
-    "company",
 ];
 export function isPeopleWorkspaceCommand(sub) {
     return (!!sub &&
@@ -23,7 +22,7 @@ export async function runPeopleWorkspace(slug, args) {
         ? work.shift()
         : area === "overview" || area === "sources"
             ? area
-            : `${area}.${work.shift() ?? (area === "company" ? "get" : area === "audience" ? "preview" : "list")}`;
+            : `${area}.${work.shift() ?? (area === "audience" ? "preview" : "list")}`;
     const file = takeFlag(work, "--file"), json = takeFlag(work, "--data");
     if (file && json)
         throw new CliHttpError("Use --file or --data, not both.", EXIT_USAGE, 0, "bad_request");

package/dist/commands/people.js

@@ -232,12 +232,16 @@ export async function runPeople(args) {
             const work = rest.slice(1);
             const id = requireId(work);
             const body = takeFlag(work, "--body") ?? takeFlag(work, "--note");
+            const requestKey = takeFlag(work, "--request-key");
+            const historical = takeFlag(work, "--historical");
+            if (historical !== undefined && !["true", "false"].includes(historical))
+                throw new Error("historical must be true or false.");
             assertNoUnknownFlags(work, "people");
             if (!body) {
                 console.error("Usage: frontpage people note <id> --body \"…\"");
                 return EXIT_USAGE;
             }
-            const data = await v1Post(`${base}/${encodeURIComponent(id)}/events`, { body });
+            const data = await v1Post(`${base}/${encodeURIComponent(id)}/events`, { body, requestKey, ...(historical !== undefined ? { historical: historical === "true" } : {}) });
             if (isJson()) {
                 emitOk("people", data);
                 return EXIT_OK;

package/dist/registry.js

@@ -407,6 +407,15 @@ export const COMMANDS = [
         ],
         seeAlso: ["prompt", "help content", "help site-building"],
     },
+    {
+        name: "customer-inbox",
+        summary: "Manage internal Customer Inbox settings, knowledge and human conversation handling",
+        usage: "frontpage customer-inbox get|put|post <resource> [--file <json>] [--request-key <key>] [--site <slug>] [--json]; export|download <id> --out <new-file>",
+        topics: ["content"],
+        examples: ["frontpage customer-inbox get settings", "frontpage customer-inbox put settings --file ./inbox-settings.json --request-key settings_revision_1", "frontpage customer-inbox get conversations", "frontpage customer-inbox get knowledge"],
+        flags: ["Internal plans and the site pilot apply", "Writes require a stable --request-key and a JSON file; reuse both on retries", "Human CLI access can guide, take over and reply; website-agent tools have management scope only", "Luna and 10× AI billing are fixed", "Full request examples: CUSTOMER-INBOX.md"],
+        seeAlso: ["people", "usage"],
+    },
     {
         name: "inbox",
         summary: "List leads / subscribers / orders",
@@ -461,7 +470,7 @@ export const COMMANDS = [
             "frontpage people export",
         ],
         flags: [
-            "Workspace: groups list|get|create|update|archive|restore|preview; stages create|update|reorder|archive|restore; membership get|add|remove|move|stage|advance|override|hold; rules list|get|create|update|enable|pause|archive|validate|preview|runs|retry; attachments create; import preview|start|get|retry; person permission; company get|set; audience preview; overview; sources",
+            "Workspace: groups list|get|create|update|archive|restore|preview; stages create|update|reorder|archive|restore; membership get|add|remove|move|stage|advance|override|hold; rules list|get|create|update|enable|pause|archive|validate|preview|runs|retry; attachments create; import preview|start|get|retry; person permission; audience preview; overview; sources",
             "All workspace operations accept --file JSON or --data JSON. Named flags: --id --label --name --group --stage --person --from-group --mode --color --position --terminal --enabled --hold --allowed --archived --reset --override include|exclude|auto --email-kind template|series --email-id --rule --run --cursor --limit --request-key. Boolean flags take true|false. Complex conditions/actions/mappings use JSON.",
             "CSV: --csv PATH plus --file mapping.json. import start requires a stable --request-key. Retry the same import with the same key and contents.",
             "list/export: --group GROUP_ID --stage STAGE_ID. See package PEOPLE.md for full examples and every JSON shape.",

package/llms.txt

@@ -35,3 +35,5 @@
 ## People groups, stages, rules, and imports
 
 Use `frontpage people overview`, `groups`, `stages`, `membership`, `rules`, `attachments`, `import`, and `company`. Use `frontpage mail campaign` for one-off group/stage/list audiences in Emails. Every editor action is available through these commands or `frontpage people workspace OPERATION --file payload.json`. Full operations and examples: [PEOPLE.md](./PEOPLE.md); public guide: https://frontpage.host/developers/people. Automated emails select a saved template or series. Campaigns use their own drafts.
+
+Customer Inbox (internal sites): CUSTOMER-INBOX.md. Settings, widget, knowledge, human guidance/relay, lifecycle, export/download and recovery. Website agents configure through manage_customer_inbox and must not use human credentials for conversations.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frontpage-host",
-  "version": "0.1.28",
-  "description": "Frontpage CLI — manage your site from the terminal",
+  "version": "0.1.29",
+  "description": "Frontpage CLI \u2014 manage your site from the terminal",
   "type": "module",
   "bin": {
     "frontpage": "dist/bin.js"
@@ -11,7 +11,8 @@
     "README.md",
     "AGENTS.md",
     "llms.txt",
-    "PEOPLE.md"
+    "PEOPLE.md",
+    "CUSTOMER-INBOX.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",