=== SO4AG Facts ===
Contributors: soqver
Tags: structured data, json-ld, schema, business information, woocommerce
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Publish the facts of your business in the open SO4AG format: a so4ag.json file, a "Facts and terms" page and JSON-LD.

== Description ==

Customers ask the same things before they buy, book or visit: what it costs, when you are open, how to pay, how long delivery takes, how to cancel, what the guarantee is. More and more often a program reads your website to answer for them.

SO4AG Facts lets you write these facts down once, in the administration of your site, and publish them in a form that programs read without guessing:

* a `so4ag.json` file at the address `https://your-site/so4ag.json`,
* a "Facts and terms" table on any page (block or shortcode `[so4ag_facts]`),
* the same facts as JSON-LD (schema.org) in the code of that page.

Every fact carries four things besides its value:

* **what it applies to** (for example: this price is for one hour, for private customers),
* **until when it applies** (after that date a reader treats it as history),
* **where your website states it** (the address of your price list, terms or contact page),
* **whether you state it at all**. A fact you do not state is published as "not stated". It is never written as zero, empty or "no limit".

= What the plugin does =

* **Facts of any business** (General profile of the format): operator, locations and opening hours, contacts, languages, service area, what you offer and for how much, payment methods, deposit, minimum order, booking, response and delivery times, cancellation, guarantee, trial period, capacity, minimum age, accessibility, licenses.
* **Facts of an online shop** (Retail profile): shipping prices by country and kind of delivery, free shipping threshold, delivery time, payment methods, cash on delivery fee, return period, warranty period, pickup in store.
* **Suggestions from WooCommerce.** When WooCommerce is active, one button reads your shipping zones and payment methods and prepares suggestions. They are only suggestions: you accept or dismiss each one.
* **Nothing is public without you.** Publishing needs your explicit confirmation that the facts are true. What is public is always the last revision you confirmed, never your unfinished edits.
* **Reminders.** The administration tells you when published facts are about to reach their date or have passed it.
* **Check.** One button checks the published output: the structure of the file, the dates, and that the JSON-LD carries exactly the same facts as the file.
* **llms.txt, only if you want.** The plugin can answer at `/llms.txt` with a short file that points to your facts. It is off by default and it never replaces an llms.txt you already have.

= What the plugin does not do =

* It does not promise that any assistant, search engine or other program will mention, quote or recommend your business. It publishes your facts in a form that is hard to misread; what readers do with them is up to them.
* It does not change the output of SEO plugins, your titles, your descriptions or any other structured data on your site. Its JSON-LD appears only on pages where you place the block or the shortcode.
* It adds no link, credit or badge to your public site.
* It needs no account, no license key and no paid plan. Every feature is in the plugin.
* It contacts no other server. See "Requests and privacy" below.

= The format =

SO4AG (Source Objects for AGents) 0.1 is an open, free format. The specification, the JSON Schema, the profiles, a validator and readers in JavaScript and Python are public:

* Specification: https://soqver.com/spec/so4ag/0.1/
* Mapping to JSON-LD: https://soqver.com/spec/so4ag/0.1/jsonld
* Source code of the validator and readers: https://github.com/soqvercom/so4ag
* Public validator: https://soqver.com/validator

SO4AG is an open format and a working draft. A valid file proves structure, not truth: you state the facts and stand behind them.

= Requests and privacy =

The plugin does not track anybody, sets no cookies and stores no personal data of visitors.

It makes HTTP requests only to **your own site**, and only when an administrator presses a button:

* "Check the public addresses too" requests your `so4ag.json` and your page with the facts, to see what visitors really receive.
* Turning on "llms.txt" requests your `/llms.txt` once, to make sure nothing else already answers there.

No request goes to any other server. Links to soqver.com in the admin (the manual, the public validator, the optional monitoring service) are plain links: nothing is sent unless you click them.

= Optional monitoring =

SOQVER (https://soqver.com) is a separate service by the authors of the format that can watch published facts from outside. The plugin only links to its free audit and its prices on one tab of the admin. A visible field on that tab accepts the partner code of a developer or agency; when an administrator fills it in, the code is added to those two links and nowhere else. It is empty by default and never placed on the public site.

== Installation ==

1. Install the plugin from the "Plugins" screen of WordPress and activate it. A new item **SO4AG Facts** appears in the admin menu.
2. Open the **Business** tab and check the name of your business.
3. Open the **Facts** tab and add your facts. With WooCommerce you can start with **Suggest from the shop**.
4. Open **Confirm and publish**, look the facts over, check the confirmation and publish.
5. Open **Output and check**, create or choose the page that shows the facts, publish that page and run the check.

The full manual with examples is at https://soqver.com/wordpress#manual

== Manual ==

= 1. Tell it who you are =

On the **Business** tab check the name of your business, pick the kind of business and, if you want, add registration identifiers (a scheme and a value, for example `ein` and your EIN, or `vat` and a VAT number).

= 2. Add your facts =

On the **Facts** tab pick a kind of fact and select **Add**. Every fact asks for four things:

* **The value**, or "We do not state this", or "It does not apply to us".
* **Conditions** (Applies to): only those the fact really depends on. A condition narrows a fact: a price with `customer: business` applies to businesses only. The value `any` says outright that the fact holds for every value.
* **The last day it applies** (Applies until). Each kind of fact has a longest time it can be confirmed for, for example 60 days for a price and 180 days for payment methods.
* **The page** of your website that states it. If you leave it empty, the fact is published as your own statement.

Opening hours use a fixed form: `Mo-Fr 09:00-18:00; Sa 09:00-12:00`. A "from" price has its own checkbox, so that it is never presented as the exact price.

= 3. A store with WooCommerce =

**Suggest from the shop** reads your shipping zones and payment methods and prepares suggestions: shipping prices by country with tax from your store tax rates, the free shipping threshold, local pickup and payment methods. The cash on delivery fee is left for you to enter, because WooCommerce does not store it. You accept, complete or dismiss each suggestion. Suggestions are never public.

= 4. Confirm and publish =

The **Confirm and publish** tab shows what will be public and what changed. Check the box that confirms the facts are true today and publish. From then on, anything you edit stays private until you confirm again. **Withdraw** takes the published facts down and keeps your working facts.

= 5. Show the facts on a page =

On **Output and check** create the draft page "Facts and terms", look it over, publish it and link it from your footer. On a page of your own use the "Facts and terms" block or the shortcode `[so4ag_facts]` (options: `heading="no"`, `level="h3"`).

= 6. Check and keep it current =

**Check the public addresses too** verifies the structure of the file, the dates, and that the page carries the same facts as the file. The admin warns you 14 days before a published fact reaches its date. Review prices and shipping monthly, cancellation and booking quarterly, payment methods and locations twice a year, and right away when your price list or terms change.

= The address of the file =

The file is served by WordPress at `/so4ag.json`. On most sites this works at once. If your web server answers "not found" for that address by itself, turn on pretty permalinks (Settings, Permalinks) or ask your host to pass requests for missing files to WordPress. Until then the address `/?so4ag_facts=json` works. The check on the **Output and check** tab tells you whether the address works.

== Frequently Asked Questions ==

= Do I need an account or a paid service? =

No. Entering the facts, publishing, the file, the page, the JSON-LD and the check all work in the plugin alone.

= Will this make AI assistants recommend my business? =

Nobody can promise that, and this plugin does not. It makes your facts available in a precise form, with their scope and their dates, so that a program that reads them has less room for error.

= What happens when a fact reaches its date? =

The fact stays in the file, but readers treat it as history and the table marks it as no longer valid. The administration reminds you beforehand. Check the fact, set a new date and publish again.

= I already have an llms.txt. =

The plugin leaves it alone. The **Output and check** tab shows the lines you can add to it yourself.

= Does it work with my SEO plugin? =

Yes. The plugin does not touch the output of other plugins. It adds its own JSON-LD block only to pages where you place the facts.

= What is removed when I delete the plugin? =

All its settings, the working facts and the published revision. Pages you created stay, without the table.

== Changelog ==

= 0.1.0 =
* First version: facts of the General and Retail profiles of SO4AG 0.1, suggestions from WooCommerce, confirmation before publishing, so4ag.json, block and shortcode with JSON-LD, optional llms.txt, expiry reminders, output check.
