Documentation

WebProCMS keeps a site's Privacy Policy and Terms of Service true to how the site actually works. Instead of a static legal page that drifts out of date, each page shows a live document: the code that owns each data practice contributes a clause, and the page puts together the clauses that apply at the moment it is shown. Switch on the shop and the policy gains its orders clause; add a Google Analytics ID and it names Google; turn on cookie consent and it explains the visitor's choices. The owner can still reword any single clause or add their own text, and a reworded clause is flagged when the live text it replaced changes.

How it works

Four layers:

1. Signals — PrivacySignalRegistry detects every data practice the CMS can see at runtime: which features are switched on, whether analytics sets a persistent cookie, whether a GA4 ID or tracking snippets are configured, whether any page embeds a video, which sign-in and email providers are wired up. Each signal reports whether it is active, a status line for the settings page, and the values its clauses print (retention days, provider names, …). Feature checks read the owner's switch (Features::configuredEnabled()), never the licence-gated one, so a licence lapse never churns the policy.
2. Facts — what the code can't know, recorded on Settings → Privacy & Compliance (see Manual facts below).
3. Clauses — LegalClauseRegistry holds every section and clause of both documents. Core registers its own (CoreLegalClauses); each feature module registers its clauses from its own provider (app/Features/{Name}/Support/{Name}LegalClauses.php). A clause has a condition, a body partial under resources/views/partials/legal/{privacy,terms}/ whose every sentence is a literal __() (so the shipped lang files translate it), and the list of signals it reads or describes. A clause whose condition is off is left off the page. A feature clause stays while the site still holds that feature's data, even after the feature is switched off.
4. The document — the x-dl.legal-document component (LegalDocumentAssembler) assembles the applicable clauses in the visitor's language, with the owner's wording wherever they customised a clause.

Detected signals

Each signal decides one or more clauses. Settings → Privacy & Compliance lists, under each detected practice, the clauses it puts in the policy (struck through when the clause is not on the page right now).

The cookies table is one clause built from several signals and lists every cookie and browser-storage item the site can give a visitor, each only while the site can set it: the session and XSRF-TOKEN cookies (with the real session cookie name and lifetime), wpcms_visitor and wpcms_device (the known-browser cookie Login Protection sets at sign-in) always; remember_web_* while any feature opens accounts; remember_commenters_* and wpcms_commenter while comments have social sign-in; wpcms_consent; wpcms_vid; wpcms_cart_n; wpc_aff and wpcms_dni (both marked as not controlled by the banner); wpcms_age_ok; Google Analytics' and Stripe's own cookies; a third-party row for embeds, maps, schedulers, snippets and hosted video; and a second table of browser storage (appearance, accessibility settings, pop-up memory and A/B versions, pop-up message rows, call tracking, chat state and invitation, the engagement page count, the listing sign-up gate and compare list, the search mode, push notifications). LegalCookieTableCoverageTest reads the site's own cookie and storage names out of the scripts, blades and PHP cookie constants and fails on any the table does not name — a new one needs a row, or an exemption with its reason when it never reaches a visitor.

Manual facts (Settings → Privacy & Compliance)

The Privacy Details card records the things the code can't know, stored under privacy.* Settings (the terms facts under legal.*). Saving it refreshes every live legal page.

• Legal entity name (defaults from Business settings) and privacy contact email (published in the policy, so never prefilled from the business email)
• Governing law / jurisdiction (optional; both documents use it). On a site with more than one language, an input per other language names the same place in that language (privacy.jurisdiction__{lang}, read by PrivacyFacts::jurisdiction()), so a Spanish page reads "las leyes de Arkansas, EE. UU." rather than the English place inside a Spanish sentence. Blank, or out of date after the English changed, the base value prints. It is on the settings translation surface, so translations:status reports it and translations:import / translations:fill can fill it.
• "We sell or share personal data" toggle — drives the CCPA wording
• Data retention statement (optional; replaces the generic retention paragraph)
• Other third-party services free text (CDN, fulfillment partner, …) — gets its own clause
• Last reviewed date (for the owner's records)
• Policy page slug (advanced — only if the policy lives at a non-default URL)
• Terms page URL (legal.terms_url) — where the signup consent checkbox links. Left blank, it links the page that shows the live Terms of Service, or no terms link at all when no page does. A URL naming a page of this site that visitors can't open (a draft) is passed over for the live terms page the same way, so signup never links — or records as accepted — text nobody can read.
• Minimum age, Refund window (days) and Cancellation notice (days) (legal.minimum_age, legal.refund_window_days, legal.cancellation_notice_days) — each adds its sentence to the live Terms of Service only once it is set. A refund window of 0 says purchases are not refunded; blank says nothing about refunds.

Legal pages (Settings → Privacy & Compliance)

The Legal Pages card shows one panel per document (LegalPageStatus):

Warnings shown on a panel:

• Linked elsewhere (Live text) — the site's links (the policy page slug, or the Terms page URL) point at a page that does not show the live document.
• Not linked (Legacy) — the site links somewhere else, or (terms) links nothing at all, so the signup form shows no terms link.
• On another site (Legacy) — the Terms page URL is an external link the CMS can't read.
• Out of date (Legacy) — a policy written by the retired generator whose detected services or privacy details have changed since it was generated.
• Not published (Missing) — a page shows the document, or sits where one would be created, but visitors can't open it. Create page is not offered; publish that page instead.
• Standard text / Standard text, reformatted / Your own wording (Legacy) — what the legal audit found the page to be.

Clause states are worked out exactly as the page editor works them out for the same page, from the overrides that page sees: Live text (follows the live text), Customized (the owner's wording), Live text changed (the live text the owner's wording replaced has since changed), Not checked (owner wording with no record of what it replaced — a version restore or a tool wrote it), and Not shown (the clause doesn't apply right now, with or without the owner's wording kept). "Needs review" groups the flagged ones. Customising, Use live text and Keep mine happen in the page editor — see "Legal document clauses" in docs/editor-architecture.md.

Revision history lists the latest 10 versions of each host's document, newest first; View shows the document as it read from that date, as plain text in the site's default language.

The cookie banner's Privacy policy URL (Cookie Consent → Other) follows the privacy page wherever it lives when left blank. The field's old default, /privacy-policy, counts as blank, so installs that saved it unchanged follow the page too.

Existing installs: the legal audit and switching

Installs built before the live documents carry a privacy policy and terms page of fixed text. LegacyLegalPageDetector finds them by content, not URL, comparing every rich-text body (as its own page shows it — that page's override tier over the global one, else the text baked into the tag) with what the CMS has shipped:

What the CMS shipped lives in StockLegalBodies, generated from git history by php artisan legal:build-stock-catalog (development only; --check compares it with history). Installs have no history, so the catalogue is committed. Its hashes are of LegalBodyText's forms — change those and the catalogue must be rebuilt (FORMAT).

legal:audit (daily LazyCron; report only) records the legal.audit Setting: each document's state (live, stock, likely_stock, edited, unknown, missing, external), every legacy page found — including theme pages parked by a theme switch — and, for the published owner-written page the Settings card shows for each document (so what the fleet counts is what the owner can see and dismiss there), two kinds of finding from the clauses that apply to the site (LegalAudit):

• Contradicts — the page says a sentence the clause makes false: "There is no Google Analytics" with Google Analytics on, "only strictly-necessary cookies" with a tracking cookie set, "We do not use these conversations to identify you" while chat leads go to the contact records. Precise by design; shown on the card and counted in the fleet badge.
• May be missing — the page names nothing a clause's practice would be called ("Stripe", "payment" on a site taking payments). A prompt to look, never a badge.

Each clause declares its own rules (audit: on its registration; contradicts phrases, optionally held to a flag in the clause's data, and mentions keywords). They are English sentences from the shipped text, so a site whose default language isn't English is not checked. The owner can Dismiss a finding from the card; dismissals are kept apart from the report (legal.audit_dismissed) so the next run doesn't bring them back — a contradiction is known by its sentence, so a dismissal holds when another clause comes to make the same sentence false — and Show them again restores a page's. Check again re-runs the audit at once. A legacy page the audit couldn't read (its text is not in a rich-text body, or too short to judge) says so on the card, rather than "not checked yet".

Switching a stock page — the card's Switch to the live … button (admin), or php artisan legal:migrate-pages (LegacyLegalPageMigrator):

• Replaces the old body with x-dl.legal-document in the same row on the RowDoc tree: the row keeps its slug and its section (and so its design), the document takes the body's classes (plus article-content when an old page lacked it), and a terms template's placeholder heading and button go too while still untouched.
• Re-reads the page under a lock first, validates the result (byte-identical round trip, Blade compiles, the document is in the row) before writing anything, and saves a forced page version first — the old text and its translations are one restore away. With page version history switched off it refuses rather than switch without one.
• Moves the file's modified time even within the same second, so an editor that had the old page open merges with the switch on its next save.
• Leaves alone: edited and likely-stock pages (unless --force-edited), a page whose text is in more than one row, a page already showing the live document, and parked theme pages (switch them once their theme is active again).
• Ends every run by dropping the cached copy of every page showing a live document, recording first revisions and re-running the audit — so a run killed after its write is finished by the next one. It deletes privacy.snapshot once no page shows the generated policy any more (a page left alone because the text sits in two rows still counts), and points privacy.page_slug at the live policy when it pointed at no page and exactly one page shows it.
• --dry-run lists what would switch and why the rest would not; --page= limits a run to one page (URL, slug or file). The card's button switches only its own document, even on a page that carries both, and a refusal says why (turn on page history first; or the page can't be switched automatically; or it changed since it was checked).

At update. The update after the live documents shipped switches every stock page by itself, shortly after it finishes. Its migration (swap_legacy_legal_pages_to_live) only schedules the switch (the legal.stock_switch Setting). The next 15-minute legal:refresh sweep runs the migrator, as legal:migrate-pages with no options would (ScheduledLegalSwitch). So the page walk never runs while the site shows the maintenance page, and nothing it does can fail the update.

• A sweep that finds the audit holding the lock leaves the switch for the next sweep, without using up a run.
• A run that fails is tried again on the next sweep, three runs in all. Each run is counted before it starts, so one that dies outright (a fatal error) still counts. After the third failure the switch is given up with a log line naming php artisan legal:migrate-pages.
• A run that finishes logs what it switched and why it left the rest, one line per page and document.
• The suite's own migrations schedule nothing.

The fleet health block carries the audit as legal_issues ({privacy, terms, contradictions, mentions}, absent before the first audit); the fleet badges an install with an undismissed contradiction.

Freshness, revisions and "Last updated"

A live document is assembled at render, but its public page is response-cached for days, so something has to notice when the text changes:

1. Fast path — saving a privacy fact, switching a feature (from anywhere, including the theme installer and setup wizard), or saving a Setting a clause watches refreshes every host page at the end of that request.
2. Render — a page render compares the text it just assembled with the newest revision. That is how an owner's own clause edit, which is an ordinary page save, gets dated.
3. legal:refresh — a LazyCron sweep every 15 minutes catches what no hook sees (an embed added on another page, a licence change). It first runs the stock-page switch an update scheduled, when there is one (see "At update" above).

Each change of text writes one row to the revision log (legal_revisions: document, page, row, the document's item prefix — a row can hold two copies of one document, each with its own wording and history — a hash and the plain text in the site's default language). The newest revision's date is the page's "Last updated" line, which each document can switch off in the editor. It is written in the site's timezone and the way the visitor's language writes a date ("October 6, 2026", "6 de octubre de 2026", "2026年10月6日"). The date line is never part of the hash, so the date moves only when the text does.

Adding a clause for a new feature

1. Write the body partial at resources/views/partials/legal/privacy/{name}.blade.php (or terms/): class-free semantic HTML (<p>, <ul>, <table>), every sentence a literal __().
2. Register the clause from the module's provider (app/Features/{Name}/Support/{Name}LegalClauses.php, one callAfterResolving(LegalClauseRegistry::class, …) line) into an existing section. Conditions read Features::configuredEnabled() plus a holdsData check, never Features::enabled(). Keys are lowercase snake case, never renamed once shipped.
3. If it reads a privacy signal (or a new signal you add to PrivacySignalRegistry), name it in the clause's signals. A test fails when a clause reads a signal it doesn't name, names one that doesn't exist, or a signal drives no clause.
4. A folded sub-feature (gift cards, event ticketing, proposals, contracts, popups — Features::FOLDED) has no switch of its own: key the clause on its parent feature (ecommerce, events, …). Features::configuredEnabled() of a folded key reads a Setting nothing writes, so a clause keyed on it would never appear.
5. Terms clauses go in the section that fits: purchases for anything bought or paid, bookings for appointments and rentals, programs for rewards and partner programs, accounts, content (including community rules), signatures for e-signing, disclaimers for listing accuracy.
6. A new cookie or browser-storage item a visitor can get needs a row in partials/legal/privacy/cookies-table.blade.php (LegalCookieTableCoverageTest).
7. Every new clause sentence and heading needs translating in all shipped lang/*.json before release (LegalClauseStringsTranslatedTest). In this repo that is a Sonnet subagent per locale, never Auto Translate.
8. Whether a page shows a component (a map, a pop-up message row) is read from the page files — with their shared and role rows, and the header and footer partials the site and each page use — by LegalPageScan, once per request.

Retired: Generate and AI rewrite

Earlier releases had Generate policy and Generate + rewrite with AI buttons, which wrote the whole policy as one block of fixed text into the privacy page's rich-text row. That text went stale the moment the site changed, and rewriting the whole document would have frozen every clause of a live one, so both are gone. Per-clause AI rewriting still works in the page editor, through the same save path as any other edit, so a rewritten clause is tracked like a hand-written one.

The generator itself is gone too. A policy it wrote that nobody has changed counts as stock — the privacy.snapshot Setting it left behind is read only to recognise that text — so the update switches it like any shipped body. One the owner edited stays as fixed text and shows as Legacy.

Limits / notes

• Not legal advice. The live documents describe what the CMS does, accurately and honestly, but owners in regulated industries should still have counsel review them.
• Languages. Clause text is translated by the shipped lang files and follows the visitor's language. The owner's own wording for a clause can be translated per language; a stored translation of a clause the owner has not customised is ignored, so it can never go stale.
• New installs ship the live documents. Every theme's Privacy Policy and Terms of Service page shows the live document (x-dl.legal-document), so a new site's policy and terms follow what it has switched on from the first day, and the signup checkbox links the terms page with no Terms page URL set. The row picker offers Privacy Policy and Terms of Service rows (Page Content → Content) to put either document on any page.
• A captured theme never carries an install's legal wording. themes:capture and Save as custom theme leave out every reworded clause and the owner's own section text, in every language, so installing the theme can't freeze someone else's wording onto a new site's policy. The document's design (classes, the "Last updated" toggle) is captured as usual.
• Copy-writing tools leave legal text alone. The AI site generator, the popup copywriter, the MCP copy tools and the dashboard assistant read live legal text as read-only and never write a clause.
• Existing installs: stock pages switch at update, the owner's own stay. An owner-written page shows as Legacy, with the legal audit's verdict, until someone switches it; legal:migrate-pages --force-edited does, keeping the old text in the page's history.