Document Email and Code Security billing, trials and costs

docs/7-administration/billing/security-products.md

@@ -0,0 +1,155 @@
+# Email Security and Code Security billing
+
+Email Security and Code Security have separate paid coverage. Paying for endpoint
+security or another product does not automatically buy either one. Enabling an
+extension starts setup; paid coverage requires explicit price acceptance and
+confirmation from the protection service.
+
+| Product | Paid rate | New organization trial |
+|---|---|---|
+| Email Security | $1 per protected mailbox-month | 14 days, up to 25 mailboxes |
+| Code Security | $0.80 per protected repository-month, plus the existing Cloud Security base fee | 14 days, up to 10 repositories |
+
+Trials cover the organization across its connections. Shared mailboxes and repeated
+references to the same repository count once when they have the same stable identity.
+Code includes hosted repositories and external scanner imports; container images do
+not contribute to this repository meter. Telemetry and other services remain separately
+priced. The console shows the organization's actual Cloud base fee; it is not included
+in the $0.80 rate.
+
+## Trial and coverage
+
+A new trial starts at the first protected resource. Unsubscribing, resubscribing or
+restarting a connection does not restart it. Use the server's trial deadline and
+coverage status instead of calculating entitlement from a browser clock.
+
+Organizations enabled before billing enforcement receive a fresh 14-day trial from
+the enforcement instant. Their existing protected set stays free for those 14 days,
+including sets above 25 mailboxes or 10 repositories. This exception preserves the
+existing set; it does not allow unlimited expansion or swapping in an unlimited number
+of new resources. New organizations and growth beyond that baseline follow the normal
+limits. Existing paid protection is not silently converted into a new charge without
+price acceptance.
+
+Use Email Security mailbox scope and exclusions to choose coverage. Code's scanning
+settings select repository coverage. Review resources that are discovered but not
+protected; a successful configuration save is not proof that protection has started.
+When eligibility expires, unpaid protection can pause. Configuration and existing
+data follow the product's retention policy and scheduled-deletion notices. Review
+those notices before the deadline; paying does not retroactively analyze work missed
+while coverage was paused.
+
+## Purchase and check acknowledgement
+
+In **Billing & Usage**, or the product's overview, review trial status, protected
+count, limits and the current rates. Add a payment method through the billing page
+(or use authorized invoicing), then select the price-acceptance checkbox and
+**Activate paid coverage**.
+
+Billing status requires `org.get` and `billing.ctrl`. Changing paid coverage also
+requires `user.ctrl`. Analysts without billing permission can still inspect product
+coverage and trial information through the product's read surface without access to
+payer or financial details.
+
+A request can remain **Pending** while billing or protection reconciles. Do not treat
+an HTTP success or a saved configuration as paid coverage. Refresh until the server
+reports acknowledged paid protection. A failed or unavailable response does not
+establish coverage; correct the payment method or contact support as indicated.
+An HTTP 200 mutation with `acknowledged: false` is committed but pending; poll GET
+until its control settles and protection matches the requested change. HTTP 503
+is retryable after refreshing status and does not confirm paid coverage. Activation
+may be temporarily unavailable during rollout while reads and stop remain available.
+
+The billing API uses the same routes for both products:
+
+| Operation | Route |
+|---|---|
+| Status and cost | `GET /v1/orgs/{oid}/billing/security/{product}` |
+| Accept pricing and request activation | `POST /v1/orgs/{oid}/billing/security/{product}` with `{"accept_pricing":true,"accepted_quote":<complete status.pricing_quote>}` |
+| Request paid stop | `DELETE /v1/orgs/{oid}/billing/security/{product}` |
+
+`product` is `mail_security` or `code_security`. Optional GET parameters `from` and
+`until` must be supplied together as UTC dates `YYYY-MM-DD`. The beginning is
+inclusive, the end exclusive, and the maximum range is 366 days. Without a custom
+range, use the returned billing period; an invoice interval can differ from a calendar
+month. The normalized `status` contains phase, acknowledged protection, trial limits,
+pending control, rates and costs. Fields whose authority is unavailable are omitted
+or null; do not interpret missing fields as paid or as zero cost.
+
+### Accept the exact quoted price
+
+GET returns `status.quote_guard_version: 1` and `status.pricing_quote`. All nine
+quote fields are required: `version`, `quote_id`, `product`, `currency`,
+`monthly_cents`, `days_per_month`, `cloud_base_monthly_cents`, `meter_price_id`,
+and `cloud_price_id`. Email's Cloud amount is `0` and price ID is an empty string;
+these fields are still required. Review the rates and send the entire quote unchanged
+in `accepted_quote`. Its opaque ID binds organization, payer and billing mode as
+well as prices. It accepts rates, not a fixed future population or monthly total.
+
+If pricing changed, POST returns HTTP 409 `reason: security_quote_changed` before
+recording consent or performing purchase effects. Refetch GET, review the new quote,
+and obtain fresh consent. The console clears its checkbox. Do not silently accept
+a freshly fetched replacement quote. Missing pricing or an unsupported quote guard
+pauses purchasing.
+
+With a CLI version supporting quoted purchases, save the quote you will review:
+
+```sh
+limacharlie billing security get mail_security --oid <organization-uuid> --output json > security-status.json
+python3 -c 'import json; s=json.load(open("security-status.json")); assert s["status"]["quote_guard_version"] == 1; print(json.dumps(s["status"]["pricing_quote"], indent=2))' > accepted-quote.json
+cat accepted-quote.json
+# After reviewing the quote:
+limacharlie billing security activate mail_security --accepted-quote accepted-quote.json --accept-pricing --oid <organization-uuid> --output yaml
+limacharlie billing security get mail_security --oid <organization-uuid> --output yaml
+# Explicit manual stop; then poll GET for acknowledgement:
+limacharlie billing security stop mail_security --confirm --oid <organization-uuid> --output yaml
+```
+
+Use `code_security` for Code; its quote also discloses the separate Cloud fee.
+The SDK class `limacharlie.sdk.billing.Billing` accepts `Billing(org).activate_security("mail_security", accept_pricing=True,
+accepted_quote=reviewed_quote)`, with the complete quote from
+`Billing(org).get_security("mail_security")`. Both surfaces preserve pending
+responses and API errors instead of claiming that purchase has completed.
+
+## How cost is calculated
+
+Each UTC day uses the **highest paid protected resource count** reached that day.
+Removing resources later that day does not erase the day's peak. Trials are free;
+trial observed counts do not become billable resource-days.
+
+The monthly resource rate is divided by a fixed **30** to price each resource-day.
+The billing period sums daily peaks and rounds the resulting period amount; it does
+not round each resource-day to whole cents.
+
+For example, one paid mailbox protected throughout a 31-day period contributes
+31 mailbox-days: `31 × $1 / 30 = $1.0333…`, or approximately **$1.03** before other
+charges. One repository contributes `31 × $0.80 / 30 = $0.8266…`, approximately
+**$0.83**, plus the separate Cloud base fee. A 28-day period contributes 28/30 of
+the resource's monthly rate when coverage stays constant.
+
+The console labels today's count **provisional** because its high-water mark can
+still increase. Closed days are settled separately. Accrued cost is an estimate, not
+a finalized invoice or the total across telemetry, Cloud fees, tax, discounts and
+other products. See the invoice for the final amount.
+
+## Stop, payment failure and recovery
+
+**Stop paid coverage** requests an end to future paid eligibility. Check the returned
+pending control and refresh until the protection service acknowledges the stop.
+Already accrued usage remains payable; the final day's peak is preserved. Stopping
+does not reset the trial or immediately erase configuration and data. Any remaining
+valid trial or grant can still permit unpaid coverage under its limits.
+
+Stopping Code paid coverage **keeps the separate Cloud Security subscription and
+base fee**. Stopping that subscription is a separate operation and also affects Code
+eligibility. Do not assume the repository stop removes every Cloud charge.
+
+A first failed payment does not immediately remove existing paid protection. Owners
+are notified while Stripe retries, with a maximum seven-day grace. Protection stops
+at terminal unpaid/canceled status or the grace deadline. Scheduled cancellation
+keeps coverage until its effective end. Payment recovery can resume previously
+consented, payment-suspended coverage; it does not undo a voluntary product stop.
+
+Keep the billing contact and payment method current, and inspect pending or suspended
+status promptly. Neither a payment-method update nor a callback alone proves that
+protection has resumed: verify the authoritative product acknowledgement.

docs/cloud-security/code-security/getting-started.md

@@ -233,3 +233,18 @@ If a repository stays unscanned, see [Troubleshooting](troubleshooting.md).
 - [Working with results](results.md): triage what the first scan found.
 - [Pull-request checks and push rescans](pull-requests.md): catch problems before they merge.
 - [AutoFix pull requests](autofix.md): have LimaCharlie open dependency upgrades.
+
+## Trial, coverage and billing
+
+Code Security has independent paid repository coverage: $0.80 per protected
+repository-month plus the existing Cloud Security base fee. A new organization
+receives a 14-day trial for up to 10 repositories across hosted connections and
+external imports. Container images do not contribute to the repository meter.
+Existing enabled organizations receive the fresh trial and preserved-set grant
+at enforcement; their deadline is not backdated to an old Cloud trial.
+
+In Billing & Usage or Code Security, inspect the canonical trial limit and
+acknowledged protection, choose coverage in scanning settings, and explicitly
+accept pricing to activate paid coverage. The separate Cloud entitlement and
+base fee remain distinct. See [Security product billing](../../7-administration/billing/security-products.md)
+for daily high-water marks, cost calculation, payment grace and stopping coverage.

docs/email-security/getting-started.md

@@ -26,16 +26,18 @@ A **credential** is the key the product uses to access your mail provider. A
 **secret** is the securely stored copy of that credential in LimaCharlie. A
 **connection** combines that secret with your provider and mailbox choices.
 
-!!! info "Trial limits"
-    Free-tier organizations can try Email Security for **14 days**, with up to
-    **25 mailboxes**. The clock starts when you subscribe, and resubscribing does
-    not restart it. Prepare your administrator access first. At expiry ingestion
-    pauses; data is removed 30 days later unless the organization moves off the
-    free tier. See [trial details](policy.md#plans-the-free-trial-and-the-mailbox-cap).
-
-    During private beta, limits may be reported before enforcement is enabled.
-    Check the Overview trial/coverage information (or `coverage.entitlement`
-    from the API) for the standing actually in force in your organization.
+!!! info "Trial and independent paid coverage"
+    New organizations receive **14 days** for up to **25 mailboxes**, starting
+    at the first protected mailbox. Resubscribing does not restart the trial.
+    Existing enabled organizations receive a fresh 14-day trial at enforcement
+    with their current protected set preserved. See
+    [Security product billing](../7-administration/billing/security-products.md).
+
+    Paid Email Security requires explicit pricing acceptance and protection
+    acknowledgement; endpoint security quota does not buy it. At effective trial
+    expiry unpaid ingestion may pause and data follows the product's retention
+    and scheduled-deletion policy. Check actual trial and coverage status rather
+    than assuming a configuration save establishes protection.
 
 ## 1. Enable Email Security
 

docs/email-security/policy.md

@@ -602,14 +602,14 @@ server from your verified claims rather than taken from the request.
 | Event | When the data is deleted | What cancels it |
 |---|---|---|
 | The organization unsubscribes from Email Security | **30 days** later | Resubscribing at any point inside those 30 days |
-| The organization's free trial ends and it stays on the free tier | **30 days** later | Moving the organization off the free tier at any point inside those 30 days |
+| The effective Email Security trial ends without paid coverage | **30 days** later | Acknowledged paid Email Security eligibility inside those 30 days |
 | The organization itself is deleted | Immediately | Nothing — the organization no longer exists |
 
 None of them needs anyone to ask. The 30-day delay exists so that unsubscribing
 by mistake, letting a trial lapse over a holiday, or moving billing around is
 recoverable — and undoing the thing that started the clock is all the recovery
 takes. The two cancellations are **not interchangeable**: resubscribing does not
-cancel a deletion scheduled because a trial ended, and upgrading does not cancel
+cancel a deletion scheduled because a trial ended, and paid activation does not cancel
 one scheduled because the organization unsubscribed. Each undoes only what it
 contradicts.
 
@@ -633,76 +633,51 @@ re-sent for the new date.
 
 ## Plans, the free trial, and the mailbox cap
 
-Email Security is in private beta and must be available to your organization
-before you subscribe. For an enabled organization, what differs between a
-**trial** organization and a **paid** one is how long it runs and how many
-mailboxes it protects.
-
-An organization is on the trial when it is on the LimaCharlie free tier — the
-same line the rest of the platform draws, so an organization evaluating Email
-Security and Cloud Security at once gets one answer about what it is paying for.
+Email Security must be available to your organization before setup. It has an
+independent paid product: **$1 per protected mailbox-month**, divided by 30 per
+UTC mailbox-day. Paying for endpoint security or increasing its quota does not
+activate paid Email Security. See [Security product billing](../7-administration/billing/security-products.md)
+for price acceptance, payment methods, costs and pending acknowledgements.
 
 | | Trial | Paid |
 |---|---|---|
-| Duration | **14 days** from the day Email Security was enabled | No trial duration limit |
-| Protected mailboxes | **25** | No plan-imposed mailbox cap |
-| Everything else — detections, remediation, retention, API, telemetry | Identical | Identical |
+| Duration | **14 days** from the first protected mailbox for new organizations | No trial duration limit |
+| Protected mailboxes | **25** across the organization | No trial mailbox cap |
+| Product features | Identical | Identical |
 
-These are the trial terms. During beta, a deployment can report limits before
-enforcing them. Read `coverage.entitlement` for your actual standing and
-enforcement; a reported limit alone does not prove ingestion has paused. Contact
-LimaCharlie to confirm trial or scheduled-deletion enforcement in your data
-region. Policy records and a CLI installation cannot enable server enforcement.
+Organizations enabled before enforcement get a fresh 14-day trial from the
+enforcement instant. Their existing protected set remains free for those 14 days,
+including a set above 25. The exception preserves that set; new organizations and
+expansion beyond the permitted baseline follow the standard cap.
 
 ### The 14-day clock
 
-The clock starts the day the organization first subscribes to
-`ext-email-security` and is recorded durably. **Unsubscribing and resubscribing
-does not restart it**: the clock survives an unsubscribe, so a trial is 14 days
-once rather than 14 days per subscription. Moving the organization off the free
-tier clears the limits immediately.
-
-Read the remaining time from the `entitlement` block of
-[`GET /coverage`](api-reference.md#reads): `trial_ends_at` and
-`trial_days_remaining`.
+The server records trial eligibility durably. **Unsubscribing and resubscribing
+does not restart it.** Read the canonical deadline and remaining days from the
+product coverage surface or billing status; a browser clock is not entitlement
+authority. Existing-organizations' fresh trial is a once-only grant, not a reset
+available on each subscription.
 
 ### What happens when the trial ends
 
-The same thing that happens when an organization unsubscribes, and for the same
-reason — the product stops, nothing is deleted yet:
-
-- **Ingestion pauses.** No new mail is analyzed, and the mail connections are
-  not renewed, so the provider's own watches expire on their own schedule.
-- **Nothing is deleted, and nothing is changed.** The connections, the policy
-  records and every message already analyzed are intact and follow their normal
-  [retention](#data-retention-and-deletion).
-- **Reading and acting still work.** An analyst can still search the queue, read
-  a message and remediate mail that was already ingested.
-- **The 30-day deletion clock starts**, with the notices described above.
-
-Moving the organization off the free tier resumes ingestion within about five
-minutes, and cancels the scheduled deletion. Mail delivered while ingestion was
-paused is not analyzed retroactively.
+Unpaid ingestion can pause when the effective trial expires. Configuration and
+previously analyzed mail remain subject to [data retention and deletion](#data-retention-and-deletion),
+including scheduled-deletion notices and grace. Reading and acting on retained
+messages remain available to authorized analysts. Explicit paid activation resumes
+eligible protection after acknowledgement; it does not retroactively analyze
+mail delivered while ingestion was paused.
 
 ### The 25-mailbox cap
 
-A trial organization protects up to 25 mailboxes. The cap applies to the whole
-organization, across every connected mail tenant, and it works on **activation**
-only:
-
-- Discovery still finds every mailbox in the tenant — the ones past the cap are
-  reported as `discovered` rather than `protected`, so you can see exactly how
-  much of the estate is not covered.
-- A mailbox that is already protected is **never** dropped to fit a cap. If the
-  cap is reached, further mailboxes stop being protected; the ones already being
-  watched keep being watched.
-- Use [`exclusions`](#exclusions) and the connection's `scope` to choose *which*
-  25 mailboxes matter — the executives and finance addresses attacks aim at are
-  the ones worth spending a trial on.
-
-`GET /coverage`'s `entitlement` block reports `mailbox_cap`, `mailboxes_active`,
-`mailboxes_over_cap` and `mailbox_cap_reached`, so the shortfall is a number
-rather than a discovery.
+A new trial protects up to 25 distinct mailboxes across all connections. Discovery
+can find more than the protected set. Use connection scope and
+[`exclusions`](#exclusions) to choose coverage, and inspect `GET /coverage` for
+what is actually protected. Renames and shared references use stable provider
+identities, rather than billing each address spelling separately.
+
+Read the server's actual enforcement and pending state. During rollout, a
+reported limit alone does not prove ingestion has paused. Contact support if
+reported entitlement and observed collection disagree.
 
 ### Requesting a purge