frontpage-host 0.2.11 → 0.3.0

package/AGENTS.md

@@ -127,7 +127,7 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 - Media: `frontpage media upload <file>` — images/PDF ≤25 MB, video (MP4/WebM/MOV) ≤50 MB, SVG/text ≤4 MB (sanitizing proxy). Human output prints `sitePath:` first (use that in markup — never raw blob hosts), then optional `url:`. Optional `?w=` on rasters only. **Text/CSV** uploads are inline only — **not** added to the media library and **cannot** be linked via `/__media` (`media upload --json` omits full `content`; use `inbox … --csv` for submission exports).
 - Generated images: `frontpage images generate --prompt "…"` `[--count N]` — one prompt, 1–4 variations of that same picture. Prints `sitePath:` first. Counts against AI $ and storage. Flag-off environments return 404 (`Image generation is not enabled.`). Do not call xAI / Imagine yourself.
 - Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
-- People CRM: `frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|tag|export`. Site-scoped person graph (email or phone). Inbox stays the raw ledger. Hide is not forget. List export is CSV (not a one-person legal dump). Full guide: https://frontpage.host/developers/people
+- People CRM: `frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|export`. Site-scoped person graph (email or phone). Inbox stays the raw ledger. Hide is not forget. List export is CSV (not a one-person legal dump). Full guide: https://frontpage.host/developers/people
 - Routines: `frontpage routines list|get|add|set|pause|resume|rm|run|runs`. One routine can hold several hours and several days. `8am,12pm,4pm` on `tue,thu,fri` stores hours `[8, 12, 16]` and weekdays `[2, 4, 5]`. Ask for an IANA timezone. Do not guess UTC. Full guide: https://frontpage.host/developers/routines
 - Store catalog: `frontpage store items|variants|categories|settings|orders|import`. Integer cents only (`$49.99` is `4999`). `--price-cents` is the usual cost. Optional `--discount-cents` is the sale the buyer pays (must be lower). End a sale with `frontpage store variants update <itemId> --id <variantId> --clear-discount`. This sends discountPriceCents: null and keeps the regular price. Omit both sale flags on update to preserve the current sale. Do not combine --clear-discount with --discount-cents; 0 means free, not removal. Read the item back to verify. Stock: use --stock unlimited on variants update or items stock --set unlimited; zero is sold out. Omit stock on update to preserve it. Rename option types or return to one SKU with items update --file, preserving the surviving variant’s regular price, sale and stock. Create a category before assigning it. Photos are a site path `/__media/uploads/<this-slug>/…` or an HTTPS URL already saved on this site. `frontpage payments connect [--no-open]` opens Frontpage then Stripe. Store always uses Add to cart. Use Payments for standalone Pay now and invoices. Service fee is `settings set-checkout-fee`. The cart starts hidden. Product pages are the default: unless they said they do not want product pages, write one `src/pages/products/item.astro` (or shop) with `data-fp-store-product`. If they said no, skip that file and do not bind `href` or `url`. Description is a small markdown subset; product-page bind is `<div data-fp-store-bind="description">`. Every store control carries `data-fp-requires="store"`. Do not bake titles or prices. Full guide: https://frontpage.host/developers/store
 
@@ -255,8 +255,12 @@ 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.
+New owner-added and CSV-imported contacts default to allowed for marketing. Explicit unknown/not_allowed choices and saved refusals, unsubscribes and delivery restrictions still apply. Imports keep their accepted policy on retry. `mail people --json` returns a specific `reasonCode` for unavailable recipients.
 
+Use `frontpage people overview`, `groups`, `stages`, `membership`, `rules`, `attachments`, `import`. 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.
+
+
+Manual group selection uses `groups.people` (20 per page, phone-only contacts included, no email-permission filter) and `membership.addMany` (1 to 20 IDs, real per-person outcomes, safe retries). Use these through `frontpage people workspace OPERATION --file payload.json`; existing CLI versions support that route. Conditional groups use the read-only `groups.preview`, with `checked`, `unknown`, cursor/limit and optional `expectedConditions` to detect changes between pages. Do not turn a conditional preview into additions or exceptions. See PEOPLE.md for mode changes, partial results and bounds.
 
 ## Customer Inbox
 
@@ -277,3 +281,7 @@ Customer Inbox team guidance: administrators may set `guidanceEmail` through the
 ## Emails workspace workflows
 
 See [MAIL.md](./MAIL.md) for the complete save contract, reusable people picker directory, saved campaign recipients, Off-series enrollment and resume timing, all sender settings/null resets, suppression rules, Sent queries and details, and retry-safe examples. `frontpage mail save --file save.json` saves template and pending series together; it never sends. `frontpage mail people` reads the same site-scoped directory as the workspace. Use `frontpage help mail --json` for current commands and flags. No new CLI binary, API namespace or migration command is required. Hosted guides and article help must be updated through the Frontpage CLI.
+
+Rule placement: read a rule revision, then use `people workspace rules.place` with `id`, `owner` and `expectedRevision`. This only organizes the rule; it does not change its trigger or execution. New UI rules/attachments save paused. Generic attachment calls still need explicit `enabled:false` for paused creation. Saved optional conditions and exact duration minutes remain supported through CLI and agent calls.
+
+Group details Email and stage email tasks use the existing `frontpage mail save` / `save_mail_editor` completion. `attachment` checks saved group/stage emailVersion, creates paused rules, supports shared-template edits with rule revisions, and recovers identical retries. Read MAIL.md, Group and stage email tasks. Template get includes ruleUsage; deletion protects paused and active rule dependencies. Creating or saving never activates, enrolls or sends.

package/MAIL.md

@@ -31,6 +31,46 @@ The response reports `complete:true` and the saved records. Keep the exact paylo
 
 The workspace's Back button returns to the source series and keeps unfinished work. A test sends only to the signed-in account in the workspace, and does not complete a step task. CLI test recipients remain explicit and subject to the existing test restrictions.
 
+## Group and stage email tasks
+
+Group details has an Email section. It shows ordinary rules whose actual trigger is someone joining that group and whose actions send a template or start a series. It uses the same records as Rules. Saved conditions and extra actions stay visible. Moving a rule's placement does not change where it runs.
+
+Use the shared Add email control to select a saved template, create a template, or use a saved series. Stage Manage rules uses the same template task. Save the group first. Creating or attaching saves one **paused** rule with no extra conditions. Nothing activates, enrolls or sends until the owner explicitly activates the rule for future events. The older `attachments.create` operation keeps its documented defaults; the new completion below always creates paused rules.
+
+The existing command and agent operation handle the complete save:
+
+- CLI: `frontpage mail save --file save.json --site YOUR_SITE --json`
+- Public API: `POST /api/v1/sites/YOUR_SITE/mail/save`
+- Agent: `save_mail_editor`
+
+First read `groups.list`. Copy the group's `emailVersion` into `attachment.expectedGroup`. For a stage, also copy its `id` and `emailVersion` into `stageId` and `expectedStage`. These are saved configuration checks; changing membership counts does not invalidate the task. Never guess a version.
+
+```json
+{
+  "requestKey": "a-stable-group-template-save",
+  "document": {
+    "kind": "template",
+    "name": "Group welcome",
+    "subject": "Welcome, {{first_name}}",
+    "preheader": "Thanks for joining us.",
+    "blocks": [{"type":"paragraph","text":"Welcome to our group."}],
+    "variables": []
+  },
+  "attachment": {
+    "groupId": "GROUP_ID_FROM_GROUPS_LIST",
+    "expectedGroup": "EXACT_EMAIL_VERSION_FROM_GROUPS_LIST"
+  }
+}
+```
+
+The response returns `complete:true`, `document` and `rule`. Repeating the same requestKey and payload returns the same pair. Changed payloads conflict. A failed transaction leaves neither a new template nor a new rule. Keep the exact request after a lost response and retry it before starting another save.
+
+To attach an existing source, omit `document`. Add either `attachment.templateId` or `attachment.seriesId` and its `expectedSourceUpdatedAt` from a fresh template/series get. A series needs at least one saved step. The result includes the source and paused rule. To edit shared content from an existing entry rule, supply the existing document with `expectedUpdatedAt`, plus `attachment.ruleId` and `expectedRevision` from `rules.get`. This saves the content while leaving the rule's conditions, actions, version, enabled state, activation time and history unchanged. Stale group, stage, source or rule checks return a conflict; keep the draft and review the saved records before making a revised request.
+
+The workspace uses the existing template editor and returns to the source group or Stages after Save & return. Group, rule, stage, picker and template drafts use private recovery scoped to the signed-in user, site and browser tab. Duplicated tabs copy the recovery snapshot once and then save separately. Cancel uses the shared unsaved-changes confirmation. An unconfirmed completion must be recovered before leaving its task. A self-test sends only test content and does not complete a pending group task.
+
+Templates remain shared. Changes affect future uses; already queued messages keep their content snapshots. Template get exposes `ruleUsage`; the UI also shows rule usage beside existing dependencies. Deleting a template used by a live rule, including a paused rule, fails with a conflict naming the rule. Remove the template action or archive the rule first. Series, form and receipt dependencies still apply. Archiving a rule keeps its run history and saved actions. Never activate, enroll or send without the user's instruction.
+
 ## Campaign recipients
 
 Include `audience` with a one_off document in the same `mail save` request. Supported keys are `personIds`, `groupIds`, `stageIds`, `filters`, and `addresses`. Use `audience:null` to clear the saved selection. Addresses normalize to lower case. Saving addresses never creates CRM people or records consent. Recipient-only edits count as changes and save with the campaign.
@@ -83,3 +123,13 @@ Types: campaign, series, confirmation, template, test, inline. Search matches re
 The owner agent uses the same services through save_mail_editor, get_mail_people, get_mail_send, update_mail_series, set_mail_series_steps, set_mail_settings and the existing send/preview/enrollment tools. remove_mail_suppression matches the CLI's existing authorized removal. Discuss and Build register the same Email capabilities. Tool schemas and runtime instructions describe complete saves, Off enrollment, waiting/resume timing, all settings/null resets, history filters and retry handling. The agent never takes site authority from model input.
 
 Hosted developer guides and article bodies must be updated through the supported Frontpage CLI, using current base revisions. Never edit a customer site's Git branch or invent a second API version for this cutover.
+
+The people directory returns `reasonCode`: `allowed`, `permission_missing`, `not_allowed`, `unsubscribed`, `delivery_restricted`, or `no_active_email`. These explain the shared marketing permission decision; selecting people never changes it. New owner additions and CSV imports default to allowed. Explicit refusals, unsubscribes and delivery restrictions still block sending.
+
+## People audience and activity
+
+People can copy a saved template into an independent campaign, review an entire group/stage/filter audience for one-time series enrollment, and read paged CRM/email history. Use `people workspace series.preview` with `audience`, then the returned exact enrollment batches. Use `people workspace person.activity` with personId and cursor for history. See [PEOPLE.md](./PEOPLE.md#full-audience-series-review-and-person-activity) for limits, receipts, identity and status rules. Saving a draft never sends or enrolls.
+
+## MCP People and email permission
+
+MCP source access alone cannot read or change email or contacts. Request separate `crm:read` / `crm:write` scopes and choose the matching People and email consent. Existing source-only grants remain unchanged. The shared tools are `frontpage_mail_read`, `frontpage_mail_write`, `frontpage_people_read`, and `frontpage_people_write`; they reuse current services and enforce the same role, plan, permission, saved-version and receipt checks. See the People guide's MCP contract for operation names, paging and uncertain-write recovery. Send, enrollment and activation require the user's instruction.

package/PEOPLE.md

@@ -6,7 +6,7 @@ People keeps a business’s contacts, notes, follow-ups, and history together. G
 
 ## Get started
 
-Use the current `frontpage-host` CLI. Sign in, then choose a site using `--site` on each command or `frontpage use YOUR_SITE`. A site is its subdomain slug, such as `acme`, not a full URL or UUID.
+Use `frontpage-host` 0.3.0 or later. Sign in, then choose a site using `--site` on each command or `frontpage use YOUR_SITE`. A site is its subdomain slug, such as `acme`, not a full URL or UUID.
 
 ```
 npm install -g frontpage-host@latest
@@ -43,12 +43,14 @@ frontpage people unhide PERSON_ID --site YOUR_SITE --json
 - **Details:** name, email, phone, mailing address, original source, first seen, and last seen. Address fields include recipient name, line 1, line 2, city, region, postal code, and country.
 - **Notes:** `people note PERSON_ID --body "…"` adds a manual note. `people rm-note PERSON_ID --event NOTE_EVENT_ID` removes an owner’s manual note. Source submissions and payments are not removable notes.
 - **Follow-up:** set an ISO date with `--at`; clear it with `people follow-up PERSON_ID --clear`. The person page highlights overdue dates.
-- **Activity:** `people get` returns the recent 50 events. The person page shows only populated categories with counts. Group and stage pages do not show a separate activity feed.
+- **Activity:** `people get` retains its recent 50 CRM events. Use `person.activity` for paged CRM and email history. The person page shows populated categories with loaded counts. Group and stage pages do not show a separate activity feed.
 - **Hide and restore:** hide is recoverable. It retains identity, history, and membership. It excludes the person from campaign audiences and automated emails. Later source ingest may restore them.
 
 ### Find and export people
 
-`people list` and `people export` accept search, group, stage, source, form, follow-up, hidden state, sort, recency, and legacy status/tag filters. List defaults to 50 contacts, supports up to 200 per page, and returns `nextCursor`. Pass that cursor to `--cursor` to continue. Export writes UTF-8 CSV; it is a contact export, not a complete activity archive.
+People list and detail reads include `eligible` and `reasonCode`. The UI shows **Can email** or **Can't email** from the same policy used by the email picker. Codes are `allowed`, `no_active_email`, `delivery_restricted`, `unsubscribed`, `not_allowed`, and `permission_missing`. Hidden or missing/invalid email addresses use `no_active_email`. These read fields do not grant consent or promise sender readiness, budget, or delivery. API, `people list --json`, `people get --json`, `list_people`, and `get_person` return the same fields. CSV now includes groups and stages instead of the retired global status/tag columns.
+
+`people list` and `people export` accept search, group, stage, source, form, follow-up, hidden state, sort and recency. List defaults to 50 contacts, supports up to 200 per page, and returns `nextCursor`. Pass that cursor to `--cursor` to continue. Export writes UTF-8 CSV; it is a contact export, not a complete activity archive.
 
 ## Groups: organize people
 
@@ -70,6 +72,25 @@ frontpage people groups archive --id GROUP_ID --site YOUR_SITE --json
 frontpage people groups restore --id GROUP_ID --site YOUR_SITE --json
 ```
 
+### Select people from a manual group
+
+The group header offers **Add people** for manual groups and **View matching people** for conditional groups. Membership selection includes visible phone-only contacts and people without marketing permission. Current members are marked **Already in this group** and cannot be selected.
+
+Use `groups.people` with `groupId`, optional `q`, `source`, `sort` (`newest`, `oldest`, `name`), `page`, `selectedOnly` and `selected` IDs. It returns 20 people per page, a full filtered `total`, the actual `page`, phone/email contact details and `member`. It rejects conditional or archived groups and never records consent.
+
+Use `membership.addMany` with `groupId` and 1 to 20 `personIds` per request. The UI can select up to 100 and submits batches of 20. Results include `added`, `alreadyMember`, `skipped`, `failed` and per-person `results` with `personId`, `status` and an optional message. Retry unconfirmed or failed IDs: current members are skipped without resetting their stage or repeating join events. Hidden people are skipped; a group that changed to conditional or archived cannot receive new additions through this operation. Successful additions save immediately and keep the normal entry rules. This does not grant email permission or change other groups.
+
+```
+frontpage people workspace groups.people --group GROUP_ID --data '{"page":1,"q":"Alex"}' --site YOUR_SITE --json
+frontpage people workspace membership.addMany --file selected-people.json --site YOUR_SITE --json
+```
+
+`selected-people.json` contains `{"groupId":"GROUP_ID","personIds":["PERSON_ID"]}`. Keep batches bounded and retain failed/unconfirmed selections for retry. Existing single-person membership and exception operations keep their current behavior.
+
+`groups.preview` accepts `limit` (1 to 200, default 200) and `cursor`, and returns `checked`, `unknown`, `matches` and `nextCursor`. A page can have no matches while more people remain to check. Counts describe the people checked so far, not saved membership. Match rows include phone as well as email. Pass `expectedConditions` with a saved group ID to reject a changed condition/mode between pages. Explicit `conditions` previews edits without saving them. Neither preview changes membership or sends emails.
+
+When changing to **Match conditions**, membership will update to match the conditions, and some people may join or leave. When changing to **Add people**, current members stay and the group stops updating from conditions. Existing exceptions, saved pauses, stages and history stay saved. The UI shows this effect before Save and does not add a confirmation step.
+
 ### Keep a group matched to conditions
 
 An automatic group uses saved contact facts. The worker checks contacts in rotating batches and updates membership as those facts or time change. Preview first. Save this as `repeat-buyers.json`:
@@ -111,7 +132,7 @@ frontpage people membership hold --person PERSON_ID --group GROUP_ID --hold fals
 
 **Preserve existing records.**
 
-Existing tags become manual groups. Existing statuses become stages in Customer progress. Setup keeps person IDs, notes, follow-ups, hidden state, and history, and sends no email. Old tag/status CLI commands remain supported. New integrations should use group and stage IDs.
+Groups and stages are the only membership and progress model. Use group and stage IDs. Global status/tag fields, filters and commands are retired. Existing groups, stages, memberships, person IDs and history remain saved. Reads never initialize or convert records. Authorized creation and ingestion set up new sites directly in the current model.
 
 Archive groups instead of deleting their history. Assignments stay saved; related rules pause. Restoring a group does not reactivate those rules. Review and activate them explicitly.
 
@@ -185,6 +206,23 @@ frontpage people rules retry --run RUN_ID --site YOUR_SITE --json
 frontpage people rules archive --id RULE_ID --site YOUR_SITE --json
 ```
 
+### Organize rules under a group or stage
+
+The stage table opens **Manage rules** without leaving the group. Create a new paused rule, place an existing rule here, or attach a saved email as a paused entry rule. The Rules tab lists group and stage rules together and can filter by placement. The editor shows the real event and ordered actions. Placement never changes the event that starts a rule.
+
+`rules.get`, `rules.list`, and `overview` return an opaque `revision` for each rule. To change only `trigger.owner`, call `rules.place` with `id`, `expectedRevision`, and `owner` (`groupId`, optional `stageId`). Use `owner:null` to restore placement inferred from the actual trigger/action groups. It accepts no execution edits. Read the latest rule again after a conflict or an uncertain response before deciding whether to retry.
+
+```bash
+frontpage people rules get --id RULE_ID --site YOUR_SITE --json
+frontpage people workspace rules.place --file placement.json --site YOUR_SITE --json
+```
+
+`placement.json` contains `{"id":"RULE_ID","expectedRevision":"REVISION_FROM_READ","owner":{"groupId":"GROUP_ID","stageId":"STAGE_ID"}}`.
+
+Placement validates active same-site references and rejects stale revisions with HTTP 409. It preserves the actual trigger, name, conditions, actions, enabled state, execution version, activation time, errors, existing run receipts and scheduled work. It changes only `trigger.owner` and the edit timestamp. General `rules.update` accepts optional `expectedRevision`. Send it to detect conflicting edits. Use general updates for intentional execution changes, which retain their existing version/activation behavior.
+
+New UI rules and email attachments save paused; activate them separately. The generic attachment API still defaults to active when `enabled` is omitted, so integrations that want a review step must send `enabled:false`. The UI removes optional condition authoring but shows existing conditions and saves them unchanged. CLI and agent condition support remains available. Duration controls store exact whole minutes while offering minutes, hours, days and weeks; saved non-round values stay exact.
+
 `trigger.owner` only places the rule in the editor. It never limits who can start the event. A form rule can belong to a stage without requiring the form submission to contain a group ID. Use `conditions` to limit it to existing members. Use `trigger.groupId` and `trigger.stageId` for membership events themselves.
 
 ### When: choose a real event
@@ -347,7 +385,7 @@ Permission belongs to the email address and site. Groups and stages never grant
 | 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. |
+| CSV import | Allowed by default; an explicit list-wide choice or row value can select otherwise | 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. |
 
@@ -409,7 +447,7 @@ 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.
+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 uses the same public API and `manage_people` operation.
 
 ## Safe sync through public customer commands
 
@@ -441,7 +479,7 @@ Alex Rivera,alex@example.com,,
 Phone customer,,+12025550199,
 ```
 
-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.
+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 allowed for new imports. The accepted import stores its effective policy, so retries keep the original choice. List-wide choices never change existing decisions. Imports preserve saved refusals, unsubscribe and suppression. Changing the list choice requires a new request key.
 
 ```
 {
@@ -454,7 +492,7 @@ Map exact header names in `mapping.json`. The permission column is optional. `ye
   "groupIds": [
     "GROUP_ID"
   ],
-  "emailPermission": "unknown"
+  "emailPermission": "allowed"
 }
 ```
 
@@ -488,7 +526,7 @@ The worker saves its cursor and each row’s outcome, so closing the editor does
 
 ## Email all people, a group, a stage, or selected people
 
-The People button names the selected audience, such as **Email all people** or **Email Newsletter**. It opens a one-off draft in Emails. Drafting and sending stay there. A campaign does not use a template as starting content.
+The People button names the selected audience, such as **Email all people** or **Email Newsletter**. It opens a one-off draft in Emails. Drafting and sending stay there. Use a template creates an independent campaign draft; editing it never changes its source template.
 
 Save `audience.json`:
 
@@ -582,7 +620,7 @@ The agent can create and edit saved templates and series with the existing Email
 
 | Operation                                  | Payload fields                                                      | Purpose                                                                                  |
 | ------------------------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| overview                                   | —                                                                   | Active groups, stages, rules, saved emails, series, and setup state.                     |
+| overview                                   | —                                                                   | Active groups, stages, rules, saved emails and series. Reads never initialize records.                     |
 | sources                                    | —                                                                   | Supported events and current form/product IDs.                                           |
 | groups.list                                | archived?                                                           | List groups; archived:true includes archived groups.                                     |
 | groups.get                                 | id                                                                  | One group with its stages.                                                               |
@@ -590,11 +628,13 @@ The agent can create and edit saved templates and series with the existing Email
 | groups.update                              | id, changed fields                                                  | Edit a group without changing its ID.                                                    |
 | groups.archive / groups.restore            | id                                                                  | Archive or restore a group. Related rules remain paused on restore.                      |
 | groups.preview                             | id or conditions; personId? or cursor?                              | Check conditions without changing membership.                                            |
+| groups.people | groupId; q?, source?, sort?, page?, selectedOnly?, selected? | Read the manual-group picker, including phone-only contacts and current membership. |
 | stages.create                              | groupId, label, color?, position?, terminal?                        | Create a stage in a saved group.                                                         |
 | stages.update                              | id, groupId, changed fields                                         | Edit a stage.                                                                            |
 | stages.reorder                             | groupId, stageIds                                                   | Save every active stage ID in order, once each.                                          |
 | stages.archive / stages.restore            | id, groupId                                                         | Keep assignments and history while archiving or restoring.                               |
 | membership.get                             | personId                                                            | Memberships and email eligibility.                                                       |
+| membership.addMany | groupId, personIds (1 to 20) | Add visible people to a manual group, reporting real per-person outcomes; retries preserve current members. |
 | membership.add / membership.remove         | personId, groupId; reset? on add                                    | Join or leave a group; a conditions group stores an include or exclude exception.                                                            |
 | membership.move                            | personId, fromGroupId, groupId, reset?                              | Leave one manual group and join another.                                                 |
 | membership.stage                           | personId, groupId, stageId                                          | Set a stage; null clears it without leaving the group.                                   |
@@ -605,6 +645,7 @@ The agent can create and edit saved templates and series with the existing Email
 | rules.get                                  | id                                                                  | Read the saved rule and version.                                                         |
 | rules.create                               | name, trigger, conditions?, actions, enabled?                       | Create a rule. Pass enabled:false to review it first.                                    |
 | rules.update                               | id, changed fields                                                  | Save a new rule version.                                                                 |
+| rules.place | id, owner, expectedRevision | Change display placement only; preserve execution and reject stale saves. |
 | rules.enable / rules.pause / rules.archive | id                                                                  | Activate future events, pause, or archive.                                               |
 | rules.validate                             | rule fields or id                                                   | Validate references and automation cycles without saving.                                |
 | rules.preview                              | rule fields or id; personId?                                        | Evaluate a person or return validation only; sends nothing.                              |
@@ -648,3 +689,86 @@ To enrol, copy each returned batch's `personIds` and `reviewToken` into `series.
 Manual series enrollment uses selected person IDs and saved steps. Off records real enrollment waiting at step 1, without a send, snapshot, timer or allowance reservation; no second Save series is needed. On starts the first email subject to sender, permission, send window and allowance checks. Turning On resumes existing people at their next unsent step with its due date intact; later waits start after successful sends. Review returns status, exclusions and nullable remainingAllowance (null while Off). It never activates a series or restarts existing, completed or cancelled enrollment, including a person whose email changed. Delivery rechecks saved restrictions. Contact groups and permission stay unchanged. Campaign recipient intent also supports explicit addresses and null to clear; saving never sends or grants consent.
 
 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.
+
+## Group and stage email tasks
+
+Group details has an Email section. It shows ordinary rules whose actual trigger is someone joining that group and whose actions send a template or start a series. It uses the same records as Rules. Saved conditions and extra actions stay visible. Moving a rule's placement does not change where it runs.
+
+Use the shared Add email control to select a saved template, create a template, or use a saved series. Stage Manage rules uses the same template task. Save the group first. Creating or attaching saves one **paused** rule with no extra conditions. Nothing activates, enrolls or sends until the owner explicitly activates the rule for future events. The older `attachments.create` operation keeps its documented defaults; the new completion below always creates paused rules.
+
+The existing command and agent operation handle the complete save:
+
+- CLI: `frontpage mail save --file save.json --site YOUR_SITE --json`
+- Public API: `POST /api/v1/sites/YOUR_SITE/mail/save`
+- Agent: `save_mail_editor`
+
+First read `groups.list`. Copy the group's `emailVersion` into `attachment.expectedGroup`. For a stage, also copy its `id` and `emailVersion` into `stageId` and `expectedStage`. These are saved configuration checks; changing membership counts does not invalidate the task. Never guess a version.
+
+```json
+{
+  "requestKey": "a-stable-group-template-save",
+  "document": {
+    "kind": "template",
+    "name": "Group welcome",
+    "subject": "Welcome, {{first_name}}",
+    "preheader": "Thanks for joining us.",
+    "blocks": [{"type":"paragraph","text":"Welcome to our group."}],
+    "variables": []
+  },
+  "attachment": {
+    "groupId": "GROUP_ID_FROM_GROUPS_LIST",
+    "expectedGroup": "EXACT_EMAIL_VERSION_FROM_GROUPS_LIST"
+  }
+}
+```
+
+The response returns `complete:true`, `document` and `rule`. Repeating the same requestKey and payload returns the same pair. Changed payloads conflict. A failed transaction leaves neither a new template nor a new rule. Keep the exact request after a lost response and retry it before starting another save.
+
+To attach an existing source, omit `document`. Add either `attachment.templateId` or `attachment.seriesId` and its `expectedSourceUpdatedAt` from a fresh template/series get. A series needs at least one saved step. The result includes the source and paused rule. To edit shared content from an existing entry rule, supply the existing document with `expectedUpdatedAt`, plus `attachment.ruleId` and `expectedRevision` from `rules.get`. This saves the content while leaving the rule's conditions, actions, version, enabled state, activation time and history unchanged. Stale group, stage, source or rule checks return a conflict; keep the draft and review the saved records before making a revised request.
+
+The workspace uses the existing template editor and returns to the source group or Stages after Save & return. Group, rule, stage, picker and template drafts use private recovery scoped to the signed-in user, site and browser tab. Duplicated tabs copy the recovery snapshot once and then save separately. Cancel uses the shared unsaved-changes confirmation. An unconfirmed completion must be recovered before leaving its task. A self-test sends only test content and does not complete a pending group task.
+
+Templates remain shared. Changes affect future uses; already queued messages keep their content snapshots. Template get exposes `ruleUsage`; the UI also shows rule usage beside existing dependencies. Deleting a template used by a live rule, including a paused rule, fails with a conflict naming the rule. Remove the template action or archive the rule first. Series, form and receipt dependencies still apply. Archiving a rule keeps its run history and saved actions. Never activate, enroll or send without the user's instruction.
+
+## Full audience series review and person activity
+
+`series.preview` accepts either the existing `personIds` array (up to 1,000 IDs) or an `audience` object, never both. Audience uses the existing People matcher: `personIds`, `groupIds`, `stageIds`, and supported `filters`. ID lists combine as a union; filters narrow the result. All people uses `{"filters":{}}`. Series audiences cannot contain `addresses`. Group/stage IDs must belong to this site and remain available.
+
+The service resolves the whole audience at explicit review, up to 10,000 people, without using the list's page or sort. It returns the existing counts, eligiblePeople, excluded reasons and reviewed batches. An empty matched audience returns zero counts and no batches. The UI keeps the eligible total and omits exclusion details; CLI/agent responses retain reasons.
+
+```bash
+frontpage people workspace series.preview --site YOUR_SITE --data '{"seriesId":"SERIES_ID","audience":{"groupIds":["GROUP_ID"],"filters":{"q":"Alex"}}}' --json
+frontpage people workspace person.activity --site YOUR_SITE --data '{"personId":"PERSON_ID","limit":50}' --json
+```
+
+Copy each returned batch's exact `personIds` and `reviewToken` into `series.enrol`, with the series ID and a unique stable requestKey for that batch. Keep completed batches and retry uncertain batches with the original payload and key. Reusing a key with other IDs conflicts. Existing and completed/cancelled enrollments never restart. Off waits at step 1 without sending; On uses the existing sender, permission, window and allowance checks. This is a one-time selection captured at review: later membership changes do not add or cancel manual enrollments. Use an explicit group-entry rule for later entrants. Never enroll or send without the user's instruction.
+
+`person.activity` is a read-only People workspace operation shared by UI, CLI, public API and agent. It returns `events`, `total`, and `nextCursor`; limit defaults to 50 and accepts 1–100. Pass the same personId and returned cursor to load older entries. Cursors keep timestamp precision and tie-break by stable entry identity; a cursor from another person/site is invalid. Queue time fixes email ordering, so delivery updates do not move it into another page. Totals are current reads and can change as activity arrives. UI tab counts refer to loaded entries.
+
+The feed combines CRM history and mail ledger rows. Mail entries use `id: "mail:SEND_ID"`, `type: "email.send"`, and payload containing sendId, subject, recipient snapshot, kind, test, status, error and status update time. Read `frontpage mail sends get --id SEND_ID` for saved content and source details. Workspace links open that same saved send even when the source was deleted. `sent` means provider accepted; only `delivered` means a saved delivery confirmation. Drafts and waiting enrollments are not sends.
+
+A saved send snapshot's crmPersonId supplies identity. Missing identity remains unbound; the read never guesses from today's email address. New series enrollments also save their person identity before any email is queued. It shows an explicitly linked CRM email event only once through the ledger. New campaign recipient snapshots retain the approved person ID, and queueing skips a recipient whose address moved to another person. Existing queued content, permission checks, group-removal rules and suppression behavior stay in place.
+
+## Groups and stages cutover
+
+Groups and optional stages are the only membership/progress model. The global status/tag API routes, tool names and CLI flags are retired. Use `--group`/`--stage`, `membership.add`/`remove` and `membership.stage`. Exports include group and stage labels; they omit global status and tags. Saved historical events still display their original facts.
+
+Opening overview, list, summary, activity or export does not initialize records. Authorized first creation or ingestion sets up a new site's normal progress group and stages. Existing default group IDs, assignments, permissions, paused work and rule receipts remain saved.
+
+### MCP access requires separate consent
+
+Source-file access does not grant contact access. Request `sites:read crm:read` for People/email reads, or `sites:read crm:read crm:write` for management. Choose People and email access on the consent screen. It defaults to **No People or email access**. Existing connections do not gain these scopes. Management can send email or activate automation on the user's instruction; site role, plan, permission and delivery checks still apply.
+
+- `frontpage_get_crm_docs`: read the current `people` or `mail` operation guide with bounded text paging. It shares no customer data.
+- `frontpage_people_read`: every shared read operation, plus `contacts.list`, `contacts.get`, `contacts.summary`, `contacts.export`.
+- `frontpage_people_write`: every shared write operation, plus `contacts.add`, `contacts.update`, `contacts.hide`, `contacts.unhide`, `contacts.followUp`, `contacts.notes.add`, `contacts.notes.remove`.
+- `frontpage_mail_read`: existing read/preview Email tool names, `get_mail_settings`, `campaign.get`, `campaign.preview`.
+- `frontpage_mail_write`: existing Email write tool names, `campaign.audience`, `campaign.send`.
+
+The four People/Mail data tools take `slug`, `operation`, and `payload`. The docs tool takes `topic`, `offset`, and `length`. The verified connection supplies site authority and actor; payload cannot override slug, siteId, actor, operation or area. Contact operations use `personId`; note removal also uses `eventId`. Follow-up uses `at` (ISO timestamp or null). Email tool names and payloads match the Mail guide and existing website-agent tools. `save_mail_editor` uses the shared receipt-backed completion. A campaign call omits the `campaign.` prefix inside its payload because operation already selects it.
+
+Read tools accept `resultOffset` (default 0) and `resultLimit` (default 50, maximum 100) to page top-level result arrays. Continue with `resultPage.nextOffset` and the same operation/payload. `resultPage.totals` records each array's full length. Native list/activity cursors belong in payload. Audience review pages recompute the read; always retain each exact returned batch and review token, and re-review after a stale-token conflict. Large records may require a smaller native limit; no result is silently truncated.
+
+Writes are not universally idempotent. Preserve documented request keys, receipts, revisions and review tokens. After an unknown outcome, read back before creating again; retry receipt-backed operations with their exact original key and payload. Never send, enroll or activate without the user's instruction.
+
+For MCP CSV exports, continue `contacts.export` with `textOffset` set to `textPage.nextOffset` and `expectedTextVersion` set to `textPage.version`. The tool returns bounded `csv` text and a version hash; a changed export returns a conflict instead of combining different snapshots. `textLength` defaults to 4,000 UTF-16 units and accepts up to 8,000.

package/README.md

@@ -2,8 +2,8 @@
 
 Frontpage CLI — manage your site from the terminal.
 
-**npm package:** `frontpage-host`  
-**Binary:** `frontpage`  
+**npm package:** `frontpage-host`
+**Binary:** `frontpage`
 **Do not install** the unrelated npm package named `frontpage`.
 
 ## Install
@@ -59,7 +59,7 @@ See [AGENTS.md](./AGENTS.md) and [llms.txt](./llms.txt) in this package.
 
 ## 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.
+Use `frontpage people overview`, `groups`, `stages`, `membership`, `rules`, `attachments`, `import`. 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.
 
 
 Payments, invoices and recurring billing: see packaged [PAYMENTS.md](./PAYMENTS.md), `frontpage help payments`, and https://frontpage.host/developers/payments. Version 0.2.0 removes writable currency, Store checkout mode and Store-owned money commands; Store stays cart-only. Preview/review before sends; keep stable operation keys on retries. Autopay requires the customer’s own verified authorization.
@@ -94,3 +94,5 @@ A whole stock count of `0` means sold out; `unlimited` sends JSON null. Omit sto
 ## Emails workspace workflows
 
 See [MAIL.md](./MAIL.md) for the complete save contract, reusable people picker directory, saved campaign recipients, Off-series enrollment and resume timing, all sender settings/null resets, suppression rules, Sent queries and details, and retry-safe examples. `frontpage mail save --file save.json` saves template and pending series together; it never sends. `frontpage mail people` reads the same site-scoped directory as the workspace. Use `frontpage help mail --json` for current commands and flags. No new CLI binary, API namespace or migration command is required. Hosted guides and article help must be updated through the Frontpage CLI.
+
+Group details Email and stage email tasks use the existing `frontpage mail save` / `save_mail_editor` completion. `attachment` checks saved group/stage emailVersion, creates paused rules, supports shared-template edits with rule revisions, and recovers identical retries. Read MAIL.md, Group and stage email tasks. Template get includes ruleUsage; deletion protects paused and active rule dependencies. Creating or saving never activates, enrolls or sends.

package/dist/commands/mail.js

@@ -123,7 +123,7 @@ export async function runMail(args) {
                 emitOk("mail", data);
             else
                 for (const p of (data.people ?? []))
-                    console.log(`${p.id}  ${p.email ?? ""}  ${p.eligible ? "eligible" : "restricted"}`);
+                    console.log(`${p.id}  ${p.email ?? ""}  ${p.eligible ? "eligible" : (p.reasonCode ?? "restricted").replaceAll("_", " ")}`);
             return EXIT_OK;
         }
         if (group === "settings") {

package/dist/commands/people.js

@@ -4,7 +4,7 @@ import { resolveSlug } from "../site.js";
 import { CliHttpError, EXIT_OK, EXIT_USAGE, apiBase, exitCodeForError, getBearerAuthHeader, httpErrorFromV1, v1Delete, v1Get, v1Patch, v1Post, } from "../http/client.js";
 import { assertNoUnknownFlags, hasFlag, takeFlag } from "../argv.js";
 import { emitErr, emitOk, isJson } from "../runtime.js";
-const USAGE = "Usage: frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|tag|export [--site <slug>] [--json]";
+const USAGE = "Usage: frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|export [--site <slug>] [--json]";
 const PERSON_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function requireId(work) {
     const fromFlag = takeFlag(work, "--id");
@@ -33,7 +33,7 @@ function displayName(row) {
     return row.name || row.email || row.phone || row.id;
 }
 function printPerson(row) {
-    const bits = [row.status ?? "—", displayName(row)];
+    const bits = [displayName(row)];
     if (row.email && row.email !== row.name)
         bits.push(row.email);
     if (row.phone && row.phone !== row.name)
@@ -47,8 +47,6 @@ function printPerson(row) {
         bits.push(`follow-up ${row.followUpAt}`);
     if (row.hiddenAt)
         bits.push("hidden");
-    if (row.tags?.length)
-        bits.push(row.tags.join(","));
     if (row.lastEvent?.summary)
         bits.push(row.lastEvent.summary);
     console.log(`${row.id}  ${bits.join("  ·  ")}`);
@@ -74,13 +72,14 @@ export async function runPeople(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
         const sub = rest[0];
+        if (sub === "tag" || args.some(arg => ["--status", "--tag"].includes(arg.split("=", 1)[0])))
+            throw new CliHttpError("Global status and tags are retired. Use people groups, membership and stages; filter with --group and --stage.", EXIT_USAGE, 400, "bad_request");
         if (isPeopleWorkspaceCommand(sub))
             return await runPeopleWorkspace(slug, rest);
         const base = `/api/v1/sites/${encodeURIComponent(slug)}/people`;
         if (!sub || sub === "list") {
             const work = sub === "list" ? rest.slice(1) : [...rest];
             const q = takeFlag(work, "--q") ?? takeFlag(work, "--query");
-            const status = takeFlag(work, "--status");
             const groupId = takeFlag(work, "--group");
             const stageId = takeFlag(work, "--stage");
             const source = takeFlag(work, "--source");
@@ -91,7 +90,6 @@ export async function runPeople(args) {
             const limit = takeFlag(work, "--limit");
             const cursor = takeFlag(work, "--cursor");
             const hidden = hasFlag(work, "--hidden");
-            const tag = takeFlag(work, "--tag");
             assertNoUnknownFlags(work, "people");
             const params = new URLSearchParams();
             if (q)
@@ -100,8 +98,6 @@ export async function runPeople(args) {
                 params.set("groupId", groupId);
             if (stageId)
                 params.set("stageId", stageId);
-            if (status)
-                params.set("status", status);
             if (source)
                 params.set("source", source);
             if (formSlug)
@@ -118,8 +114,6 @@ export async function runPeople(args) {
                 params.set("cursor", cursor);
             if (hidden)
                 params.set("hidden", "1");
-            if (tag)
-                params.set("tag", tag);
             const qs = params.toString();
             const data = await v1Get(qs ? `${base}?${qs}` : base);
             if (isJson()) {
@@ -187,7 +181,7 @@ export async function runPeople(args) {
             const work = rest.slice(1);
             const id = requireId(work);
             const body = {};
-            for (const field of ["name", "email", "phone", "notes", "status"]) {
+            for (const field of ["name", "email", "phone", "notes"]) {
                 const v = takeFlag(work, `--${field}`);
                 if (v !== undefined)
                     body[field] = v === "" ? null : v;
@@ -217,7 +211,7 @@ export async function runPeople(args) {
             }
             assertNoUnknownFlags(work, "people");
             if (Object.keys(body).length === 0) {
-                console.error("Usage: frontpage people set <id> [--name …] [--email …] [--phone …] [--notes …] [--status …] [--line1 … --city … --region … --postal … --country …] [--clear-address]");
+                console.error("Usage: frontpage people set <id> [--name …] [--email …] [--phone …] [--notes …] [--line1 … --city … --region … --postal … --country …] [--clear-address]");
                 return EXIT_USAGE;
             }
             const data = await v1Patch(`${base}/${encodeURIComponent(id)}`, body);
@@ -304,32 +298,9 @@ export async function runPeople(args) {
             console.log(`Restored ${displayName(data.person)}`);
             return EXIT_OK;
         }
-        if (sub === "tag") {
-            const work = rest.slice(1);
-            const id = requireId(work);
-            const add = takeFlag(work, "--add");
-            const remove = takeFlag(work, "--remove") ?? takeFlag(work, "--rm");
-            assertNoUnknownFlags(work, "people");
-            if ((!add && !remove) || (add && remove)) {
-                console.error("Usage: frontpage people tag <id> --add <tag> | --remove <tag>");
-                return EXIT_USAGE;
-            }
-            const data = add
-                ? await v1Post(`${base}/${encodeURIComponent(id)}/tags`, {
-                    tag: add,
-                })
-                : await v1Delete(`${base}/${encodeURIComponent(id)}/tags/${encodeURIComponent(remove)}`);
-            if (isJson()) {
-                emitOk("people", data);
-                return EXIT_OK;
-            }
-            printPerson(data.person);
-            return EXIT_OK;
-        }
         if (sub === "export") {
             const work = rest.slice(1);
             const q = takeFlag(work, "--q") ?? takeFlag(work, "--query");
-            const status = takeFlag(work, "--status");
             const groupId = takeFlag(work, "--group");
             const stageId = takeFlag(work, "--stage");
             const source = takeFlag(work, "--source");
@@ -337,7 +308,6 @@ export async function runPeople(args) {
             const followUp = takeFlag(work, "--follow-up");
             const sort = takeFlag(work, "--sort");
             const lastSeenDays = takeFlag(work, "--last-seen-days");
-            const tag = takeFlag(work, "--tag");
             const out = takeFlag(work, "--out");
             const hidden = hasFlag(work, "--hidden");
             assertNoUnknownFlags(work, "people");
@@ -348,8 +318,6 @@ export async function runPeople(args) {
                 params.set("groupId", groupId);
             if (stageId)
                 params.set("stageId", stageId);
-            if (status)
-                params.set("status", status);
             if (source)
                 params.set("source", source);
             if (formSlug)
@@ -362,8 +330,6 @@ export async function runPeople(args) {
                 params.set("lastSeenDays", lastSeenDays);
             if (hidden)
                 params.set("hidden", "1");
-            if (tag)
-                params.set("tag", tag);
             const qs = params.toString();
             const csv = await fetchPeopleCsv(qs ? `${base}/export?${qs}` : `${base}/export`);
             if (out) {

package/dist/completions/generate.js

@@ -25,7 +25,7 @@ _frontpage_completions() {
     seo|settings) COMPREPLY=( $(compgen -W "get set" -- "\${cur}") ) ;;
     articles) COMPREPLY=( $(compgen -W "list content create-section create-article set-draft" -- "\${cur}") ) ;;
     analytics) COMPREPLY=( $(compgen -W "dashboard summary query funnel timeseries compare sql" -- "\${cur}") ) ;;
-    people) COMPREPLY=( $(compgen -W "list get add set note rm-note follow-up hide unhide" -- "\${cur}") ) ;;
+    people) COMPREPLY=( $(compgen -W "overview sources groups stages membership rules attachments import person audience workspace list get add set note rm-note follow-up hide unhide export" -- "\${cur}") ) ;;
     routines) COMPREPLY=( $(compgen -W "list get add set pause resume rm run runs" -- "\${cur}") ) ;;
     buttons) COMPREPLY=( $(compgen -W "list get create update archive restore" -- "\${cur}") ) ;;
     mail) COMPREPLY=( $(compgen -W "save people campaign settings email template series send sends enrolments suppress --file --q --status --type --page --limit --cursor --source --sort --availability --selected --selected-only --offset --header-align --window-start --window-end --hourly-cap --site --json" -- "\${cur}") ) ;;
@@ -73,7 +73,7 @@ _frontpage() {
         tokens) _values 'subcommand' set ;;
         seo|settings) _values 'subcommand' get set ;;
         analytics) _values 'subcommand' dashboard summary query funnel timeseries compare sql ;;
-        people) _values 'subcommand' list get add set note rm-note follow-up hide unhide ;;
+        people) _values 'subcommand' overview sources groups stages membership rules attachments import person audience workspace list get add set note rm-note follow-up hide unhide export ;;
         routines) _values 'subcommand' list get add set pause resume rm run runs ;;
         mail) _values 'subcommand' save people campaign settings email template series send sends enrolments suppress ;;
         buttons) _values 'subcommand' list get create update archive restore ;;
@@ -114,7 +114,7 @@ export function generateFishCompletion() {
         `complete -c frontpage -n "__fish_seen_subcommand_from tokens" -a "set"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from seo settings" -a "get set"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from analytics" -a "dashboard summary query funnel timeseries compare sql"`,
-        `complete -c frontpage -n "__fish_seen_subcommand_from people" -a "list get add set note rm-note follow-up hide unhide"`,
+        `complete -c frontpage -n "__fish_seen_subcommand_from people" -a "overview sources groups stages membership rules attachments import person audience workspace list get add set note rm-note follow-up hide unhide export"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from routines" -a "list get add set pause resume rm run runs"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from mail" -a "save people campaign settings email template series send sends enrolments suppress"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from buttons" -a "list get create update archive restore"`,

package/dist/registry.js

@@ -468,7 +468,7 @@ export const COMMANDS = [
     {
         name: "people",
         summary: "People, groups, stages, rules, imports, and campaign audiences",
-        usage: "frontpage people overview|sources|groups|stages|membership|rules|attachments|import|company|person|audience|workspace … [--site <slug>] [--json]; list|get|add|set|note|rm-note|follow-up|hide|unhide|tag|export remain available",
+        usage: "frontpage people overview|sources|groups|stages|membership|rules|attachments|import|person|audience|workspace … [--site <slug>] [--json]; list|get|add|set|note|rm-note|follow-up|hide|unhide|export remain available",
         topics: ["content"],
         examples: [
             "frontpage people overview --json",
@@ -479,21 +479,19 @@ export const COMMANDS = [
             "frontpage people import start --csv customers.csv --file mapping.json --request-key REQUEST_UUID",
             "frontpage people list",
             "frontpage people add --email alex@example.com --name Alex",
-            "frontpage people set <id> --status working",
+            "frontpage people membership stage --person PERSON_ID --group GROUP_ID --stage STAGE_ID",
             'frontpage people set <id> --line1 "12 Main" --city Austin --region TX --postal 78701 --country US',
             'frontpage people note <id> --body "Called them"',
             "frontpage people follow-up <id> --at 2026-09-12T00:00:00Z",
             "frontpage people hide <id>",
-            "frontpage people tag <id> --add vip",
-            "frontpage people list --tag vip",
             "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; 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.",
+            "CSV: --csv PATH plus --file mapping.json. New contacts default to allowed; JSON emailPermission can select unknown or not_allowed. Row values override the list choice; saved refusals, unsubscribes and suppressions remain protected. 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",
+            "list: --q --group --stage --source --form-slug --follow-up due|upcoming|none --hidden --sort --last-seen-days --limit --cursor",
             "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>",
@@ -833,7 +831,7 @@ export const TOPICS = {
   frontpage media list|upload <file>   # images/PDF/video; text/CSV = inline not library; sitePath first when stored
   frontpage images generate --prompt "…" [--count N]  # 1–4 AI variations of one prompt; sitePath first; AI $ + storage
   frontpage inbox [leads|subscribers|orders|google_reviews|…] [--mark-read] [--csv]
-  frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|tag|export
+  frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|export
   # People CRM guide: https://frontpage.host/developers/people
   frontpage routines list|get|add|set|pause|resume|rm|run|runs
   # Routines guide: https://frontpage.host/developers/routines

package/llms.txt

@@ -16,7 +16,7 @@
 - Version: frontpage --version | -V | version
 - SEO get: frontpage seo get [/path|--path /path]; search path filter: [path|--path <path>]; open [/path|--path /path]
 - Redirects: frontpage redirects list|set|rm — HTTP 301/308, instant, not a file; revert does not undo; do not fake with Astro.redirect / meta refresh
-- People CRM: frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|tag|export. Site-scoped person graph (email or phone). Inbox stays the raw ledger. Hide is not forget. List export is CSV. Unknown leftover flags fail closed. Guide: https://frontpage.host/developers/people
+- People CRM: frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|export. Site-scoped person graph (email or phone). Inbox stays the raw ledger. Hide is not forget. List export is CSV. Unknown leftover flags fail closed. Guide: https://frontpage.host/developers/people
 - Routines: frontpage routines list|get|add|set|pause|resume|rm|run|runs. Several hours and several days are one routine. 8am,12pm,4pm and tue,thu,fri store hours [8, 12, 16] and weekdays [2, 4, 5]. Timezone is IANA. Do not guess UTC. Guide: https://frontpage.host/developers/routines
 - Store catalog: frontpage store items|variants|categories|settings|orders|import. Integer cents only ($49.99 is 4999). --price-cents is the usual cost. Optional --discount-cents is the sale the buyer pays (must be lower). End a sale with `frontpage store variants update <itemId> --id <variantId> --clear-discount`. This sends discountPriceCents: null and keeps the regular price. Omit both sale flags on update to preserve the current sale. Do not combine --clear-discount with --discount-cents; 0 means free, not removal. Read the item back to verify. Stock: use --stock unlimited on variants update or items stock --set unlimited; zero is sold out. Omit stock on update to preserve it. Rename option types or return to one SKU with items update --file, preserving the surviving variant’s regular price, sale and stock. Create a category before assigning it. Photos are /__media/uploads/<this-slug>/… or an HTTPS URL already saved on this site. frontpage payments connect [--no-open] opens Frontpage then Stripe. Store is cart-only; currency comes from Stripe and cannot be set. Use frontpage payments for standalone Pay now and invoices. Service fee is settings set-checkout-fee. The cart starts hidden. Product pages are the default: unless they said they do not want product pages, write one src/pages/products/item.astro (or shop) with data-fp-store-product. If they said no, skip that file and do not bind href or url. Description is a small markdown subset; product-page bind is <div data-fp-store-bind="description">. Every store control carries data-fp-requires="store". Leave data-fp-store-variants empty. Do not bake titles or prices. Guide: https://frontpage.host/developers/store
 - Analytics funnel: --steps JSON array or comma paths (/, /pricing); bad JSON → Invalid JSON for --steps
@@ -34,7 +34,9 @@
 
 ## 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.
+New owner-added and CSV-imported contacts default to allowed for marketing. Explicit unknown/not_allowed choices and saved refusals, unsubscribes and delivery restrictions still apply. Imports keep their accepted policy on retry. `mail people --json` returns a specific `reasonCode` for unavailable recipients.
+
+Use `frontpage people overview`, `groups`, `stages`, `membership`, `rules`, `attachments`, `import`. 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 (Scale and internal sites): CUSTOMER-INBOX.md. Settings, widget, knowledge, human guidance/relay, lifecycle, export/download and recovery. The owner toolbar manages all site-wide Inbox operations through manage_customer_inbox, including conversations, files and recovery, but cannot edit/unlock locked knowledge. The support agent is restricted to its verified customer and cannot change shared knowledge from customer input. No borrowed human credentials.
 
@@ -51,3 +53,5 @@ Customer Inbox: Frontpage website chat uses one settings toggle, no website edit
 ## Emails workspace workflows
 
 See [MAIL.md](./MAIL.md) for the complete save contract, reusable people picker directory, saved campaign recipients, Off-series enrollment and resume timing, all sender settings/null resets, suppression rules, Sent queries and details, and retry-safe examples. `frontpage mail save --file save.json` saves template and pending series together; it never sends. `frontpage mail people` reads the same site-scoped directory as the workspace. Use `frontpage help mail --json` for current commands and flags. No new CLI binary, API namespace or migration command is required. Hosted guides and article help must be updated through the Frontpage CLI.
+
+Group details Email and stage email tasks use the existing `frontpage mail save` / `save_mail_editor` completion. `attachment` checks saved group/stage emailVersion, creates paused rules, supports shared-template edits with rule revisions, and recovers identical retries. Read MAIL.md, Group and stage email tasks. Template get includes ruleUsage; deletion protects paused and active rule dependencies. Creating or saving never activates, enrolls or sends.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frontpage-host",
-  "version": "0.2.11",
-  "description": "Frontpage CLI \u2014 manage your site from the terminal",
+  "version": "0.3.0",
+  "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {
     "frontpage": "dist/bin.js"