frontpage-host 0.1.27 → 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

@@ -338,18 +338,95 @@ Copy the attachment’s returned rule ID before enabling it. Pass `--enabled fal
 
 See the [Email guide](/developers/mail) for content blocks, template variables, series step delays, sender settings, and email limits.
 
-## Email permission is independent of groups
+## Marketing email permission
 
-Group membership never grants email permission. A person who opts out stays in their groups and stages, while automated marketing emails and campaigns stop. Every delivery checks permission again, so an unsubscribe after audience selection still stops delivery.
+Permission belongs to the email address and site. Groups and stages never grant it. A person who opts out stays in their groups and stages. Campaign selection, rules, direct-address sends, series and delivery enforce saved withdrawals and restrictions.
+
+### Defaults and explicit choices
+
+| Entry point | New contact | Existing contact |
+| --- | --- | --- |
+| Owner UI, `people add`, public API `POST /people`, agent `add_person` | `allowed` by default, recorded as an owner assertion | Omitted choice preserves the saved decision. Explicit choices can fill unknown permission; add cannot reverse a recorded refusal, mailing-list unsubscribe or suppression. |
+| CSV import | Unknown unless an explicit list-wide choice or row value supplies permission | List-wide choices leave existing decisions alone. Row values can record permission, but cannot reverse a refusal, unsubscribe or suppression. |
+| Forms, orders, bookings and account events | Unknown unless a supported subscriber signup records agreement | Preserve saved permission; purchases and signup timestamps are not email agreement. |
+| Group, stage, name, phone, note and follow-up changes | No permission change | No permission change. Changing an email does not transfer an old address's grant; a recorded refusal stays in effect. |
+
+The add choice is `allowed`, `unknown`, or `not_allowed`. API and agent callers use the same `emailPermission` string field. CLI callers use `--email-permission`. Recording `allowed` asserts that you have permission; it does not obtain permission from the person.
 
 ```
-frontpage people person permission --person PERSON_ID --allowed false --site YOUR_SITE --json
+# New owner-added contacts default to permission given. Repeated adds preserve decisions.
+frontpage people add --email alex@example.com --site YOUR_SITE --json
+# Choose unknown when you do not have a recorded agreement:
+frontpage people add --email pat@example.com --email-permission unknown --site YOUR_SITE --json
+# Record refusal without enabling marketing:
+frontpage people add --email sam@example.com --email-permission not_allowed --site YOUR_SITE --json
 frontpage people membership get --person PERSON_ID --site YOUR_SITE --json
-# Only record permission when the person has actually given it:
+# Explicitly stop or record a new owner decision on the person:
+frontpage people person permission --person PERSON_ID --allowed false --site YOUR_SITE --json
 frontpage people person permission --person PERSON_ID --allowed true --site YOUR_SITE --json
 ```
 
-`membership.get` includes email eligibility and the reason a contact cannot receive mail. Missing email, hidden state, missing permission, saved unsubscribe, and suppression can block delivery. An owner can record a new permission decision, but cannot reverse a mailing-list unsubscribe or suppression. CSV values cannot reverse an existing opt-out, including a recorded false decision. Do not add a permission check to every group or stage; delivery already enforces it.
+`membership.get` reports eligibility and the reason mail cannot send. A missing/invalid email, hidden person, missing permission, recorded refusal, subscriber unsubscribe or suppression can block marketing. An active subscriber agreement can establish permission even without a separate CRM flag. A requested test copy can go to its test recipient without a recorded grant or a new subscription. Saved withdrawals, hidden state and suppression still apply. Transactional confirmations keep their own existing sending flow.
+
+An explicit address outside People is an owner-asserted recipient and does not create a CRM permission record. If that address matches a saved person, the normal CRM eligibility check applies. Known subscribers' unsubscribe and saved suppressions also apply when no CRM person matches. Once queued, a known person's ID stays attached so a later address change, hide or withdrawal prevents delivery. A test is not a way to send a customer campaign.
+
+New CRM decisions store state, exact email, source, actor and recording time in `attrs.emailPermissionRecord`; the boolean `attrs.emailPermission` stays compatible with existing callers. Historical grants without that record remain supported. Permission events preserve the decision history. Do not add a permission condition to every rule; the sender already checks it.
+
+### Repair reviewed historical permission without running rules
+
+Review each person's current address, agreement evidence, saved withdrawals and restrictions first. This operation only fills missing permission. It never adds a person, changes their groups/stages, clears a restriction, or replays automation.
+
+Save `repair.json` with real values:
+
+```json
+{
+  "personId": "PERSON_ID",
+  "allowed": true,
+  "backfill": true,
+  "expectedEmail": "alex@example.com",
+  "evidence": "Owner confirmed this person's marketing-email agreement on 2026-10-12",
+  "requestKey": "UNIQUE_REPAIR_UUID"
+}
+```
+
+```
+frontpage people person permission --file repair.json --site YOUR_SITE --json
+frontpage people membership get --person PERSON_ID --site YOUR_SITE --json
+```
+
+Reuse the same key and evidence after a lost response. A repeat returns `duplicate:true` without changing the decision again. If the person withdrew permission afterward, a retry does not restore it. A changed address, hidden person, existing decision, active subscriber agreement, unsubscribe or suppression refuses a new backfill. A new explicit owner decision uses the normal `allowed` operation instead; it still cannot reverse a subscriber unsubscribe or suppression.
+
+For a reviewed cohort, submit at most 25 people in each bounded batch. Each row needs its own stable request key:
+
+```json
+{
+  "allowed": true,
+  "backfill": true,
+  "evidence": "Owner confirmed marketing-email permission for this reviewed cohort",
+  "people": [
+    { "personId": "PERSON_ID", "expectedEmail": "alex@example.com", "requestKey": "UNIQUE_REPAIR_UUID" }
+  ]
+}
+```
+
+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
 
@@ -364,7 +441,7 @@ Alex Rivera,alex@example.com,,
 Phone customer,,+12025550199,
 ```
 
-Map exact header names in `mapping.json`. The permission column is optional; omit it when permission is unknown. `yes`/`true` records existing permission and `no`/`false` records no permission.
+Map exact header names in `mapping.json`. The permission column is optional. `yes`/`true` records an owner assertion and `no`/`false` records refusal. A supplied row value takes priority over the list-wide choice; duplicate rows keep a negative decision. Set top-level `emailPermission` to `allowed`, `unknown`, or `not_allowed` for new people whose row has no permission value. Omission defaults to unknown. List-wide choices never change existing decisions. Imports preserve saved refusals, unsubscribe and suppression. Changing the list choice requires a new request key.
 
 ```
 {
@@ -376,7 +453,8 @@ Map exact header names in `mapping.json`. The permission column is optional; omi
   },
   "groupIds": [
     "GROUP_ID"
-  ]
+  ],
+  "emailPermission": "unknown"
 }
 ```
 
@@ -447,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.
@@ -545,14 +611,12 @@ The agent can create and edit saved templates and series with the existing Email
 | rules.runs                                 | ruleId?, cursor?, limit?                                            | Inspect saved outcomes and failed actions.                                               |
 | rules.retry                                | runId or ruleId                                                     | Retry eligible failed work; completed action receipts stay saved.                        |
 | attachments.create                         | groupId, stageId?, emailKind, emailId, enabled?, name?, conditions? | Create an ordinary group/stage entry rule for a template or series.                      |
-| person.permission                          | personId, allowed                                                   | Record an email-permission decision; mailing-list unsubscribe and suppression still win. |
+| person.permission | personId, allowed; backfill?, expectedEmail?, evidence?, requestKey?; or backfill batch with people (1–25) | Record a decision or repair reviewed missing permission without automation. Unsubscribe and suppression still win. |
 | audience.preview                           | audience                                                            | Preview matched and eligible People for a campaign.                                      |
 | import.preview                             | csv, mapping?, headersOnly?                                         | Validate a CSV and match existing contacts; sends nothing.                               |
 | 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
 
@@ -567,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

@@ -161,6 +161,9 @@ export async function runPeople(args) {
             const phone = takeFlag(work, "--phone");
             const name = takeFlag(work, "--name");
             const note = takeFlag(work, "--note");
+            const emailPermission = takeFlag(work, "--email-permission");
+            if (emailPermission !== undefined && !["allowed", "unknown", "not_allowed"].includes(emailPermission))
+                throw new CliHttpError("--email-permission is allowed, unknown, or not_allowed.", EXIT_USAGE, 0, "bad_request");
             assertNoUnknownFlags(work, "people");
             if (!email && !phone) {
                 console.error("Usage: frontpage people add --email you@example.com | --phone +15551234567 [--name …] [--note …]");
@@ -171,6 +174,7 @@ export async function runPeople(args) {
                 phone,
                 name,
                 note,
+                ...(emailPermission !== undefined ? { emailPermission } : {}),
             });
             if (isJson()) {
                 emitOk("people", data);
@@ -228,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,12 +470,12 @@ 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.",
             "list: --q --status --source --form-slug --follow-up due|upcoming|none --hidden --sort --last-seen-days --tag --limit --cursor",
-            "add requires --email and/or --phone (never name alone)",
+            "add requires --email and/or --phone (never name alone). New contacts default to owner-asserted email permission; --email-permission allowed|unknown|not_allowed changes this choice. Existing default decisions stay saved; withdrawals/restrictions cannot be overridden by add.",
             "tag: --add <label> | --remove <slug>",
             "export writes UTF-8 CSV (same filters as list). Optional --out <file>",
             "Hide is not forget. Unique email/phone stay; later ingest un-hides",

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.27",
-  "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",