Agentic Browsing

SonoTrix add-on for CS-Cart that publishes a storefront summary for AI agents and annotates public forms so agents can use them.

Each storefront domain gets discovery URLs on one CS-Cart root:

• https://your-domain/llms.txt (virtual — never a root file)
• https://your-domain/robots.txt (virtual when enabled)
• https://your-domain/.well-known/ard.json
• https://your-domain/.well-known/ai-catalog.json
• https://your-domain/.well-known/security.txt (when Enable security.txt is on)
• https://your-domain/.well-known/assetlinks.json (when Enable Asset Links is on)

General → .well-known serving mode

Choose this on the General tab (ROOT setting, shared by all storefronts):

Virtual URLs (default)

CS-Cart serves /.well-known/* from the engine. No discovery files should exist on the server.

Required when you select Virtual:

1. Delete the CS-Cart root .well-known folder (or at least every add-on discovery file inside it: security.txt, ard.json, ai-catalog.json, search-products.schema.json, assetlinks.json, *_st{ID}.*, and the add-on .htaccess). A physical file is served by the web server for every domain and blocks the virtual route. The add-on also removes its own leftover files when Virtual is active.
2. Allow the vhost to pass these URLs to PHP so virtual responses work. Remove any trap such as:

location ~ /.well-known {
    auth_basic off;
    allow all;
}

That block never runs CS-Cart. Use pass-through locations instead (nginx example).

Important: add every location below. If only security.txt is passed to PHP, that URL works while ard.json, ai-catalog.json, assetlinks.json, and search-products.schema.json return a raw nginx 404 Not Found and never reach the add-on.

location = /robots.txt { try_files /index.php?$query_string =404; }
location = /llms.txt { try_files /index.php?$query_string =404; }
location = /.well-known/security.txt { try_files /index.php?$query_string =404; }
location = /.well-known/assetlinks.json { try_files /index.php?$query_string =404; }
location = /.well-known/ard.json { try_files /index.php?$query_string =404; }
location = /.well-known/ai-catalog.json { try_files /index.php?$query_string =404; }
location = /.well-known/search-products.schema.json { try_files /index.php?$query_string =404; }

Or one prefix block (still remove any bare location ~ /.well-known trap first):

location ^~ /.well-known/ {
    try_files $uri /index.php?$query_string;
}

On Apache, the CS-Cart root .htaccess already rewrites missing files to index.php once the static .well-known shadows are deleted.

If you cannot edit the vhost, switch to Writable .well-known folder so nginx can serve the files from disk.

Writable .well-known folder

Use when the host can only serve static files under /.well-known and you cannot change the vhost. The add-on creates the folder and stores per-storefront files, for example:

• store1.com/.well-known/security.txt → disk security_st1.txt
• store2.com/.well-known/security.txt → disk security_st2.txt
• Same pattern for ard_st{ID}.json, ai-catalog_st{ID}.json, assetlinks_st{ID}.json, and search-products.schema_st{ID}.json

The browser and crawlers always call the public names (security.txt, ard.json, …). Apache/LiteSpeed can map by host via the generated .htaccess; nginx static hosts also get plain aliases refreshed for the current storefront on page load.

/llms.txt and /robots.txt are always virtual. Do not keep static root robots.txt or llms.txt.

Install the add-on

1. Download the Agentic Browsing package.
2. Go to Add-ons → Manage add-ons.
3. Upload, install, and enable the add-on.
4. Clear the CS-Cart cache once after installation.
5. Open https://your-domain/.well-known/ard.json (virtual by default).

See also: How to Install CS-Cart Add-ons.

Configure the text

Go to Add-ons → Manage add-ons → Agentic Browsing.

General

• .well-known serving mode
  • Virtual URLs (no files on server) — default. Delete the root .well-known discovery files/folder, and configure the vhost so /.well-known/* reaches PHP (see above).
  • Writable .well-known folder — per-storefront *_st{ID}.* on disk; public URL unchanged (no vhost change required)

Each other tab starts with an enable checkbox.

On by default:

• Enable llms.txt — clear to stop publishing /llms.txt.
• Enable AI catalog — clear to stop publishing /.well-known/ard.json, /.well-known/ai-catalog.json, and the discovery links on public pages.
• Enable WebMCP — clear to leave forms unchanged and skip the product search tool.
• Enable Schema.org markup — clear so this add-on does not add structured data.
• Enable accessibility for agents — clear so controls that already have no name stay unchanged.

Off by default:

• Enable robots.txt — turn on to serve this add-on’s virtual /robots.txt for the storefront. While off, CS-Cart core robots from Website → robots (?:robots_data) still apply. Delete any physical root robots.txt so the virtual URL is not replaced by a static file.
• Enable security.txt — turn on to serve /.well-known/security.txt (RFC 9116). Virtual by default; written as security_st{ID}.txt only in writable mode.
• Enable Asset Links — turn on to serve /.well-known/assetlinks.json from settings. Virtual by default; written as assetlinks_st{ID}.json only in writable mode.

The catalog leaves out llms.txt when that tab is off, and leaves out the search schema when WebMCP is off.

llms.txt

The llms.txt markdown field is the page AI agents read at /llms.txt.

Keep:

• one title line that starts with #
• a short summary
• links written as [Home](https://your-domain/)

These tokens are replaced for the storefront that is being viewed:

Token	Replaced with
[store_name]	Storefront name
[store_url]	Storefront home page
[catalog_url]	Product search
[cart_url]	Cart
[account_url]	Customer account
[contact_url]	Storefront home page

robots.txt

Enable robots.txt is off by default. Turn it on for a storefront that should use this add-on’s robots body.

/robots.txt is a virtual URL per domain (same idea as /llms.txt). Example: store1.com/robots.txt loads that storefront’s text; store2.com/robots.txt loads the other. Delete {CS-Cart root}/robots.txt if it exists — a static root file is the same for every domain.

The default body:

• Keeps CS-Cart paths such as /app/ and /store_closed.html blocked
• Blocks duplicate-content query strings (dispatch, sort, layout, category_id, sl, and similar)
• Leaves public pretty URLs crawlable for search engines and AI/LLM crawlers under a single User-agent: * group
• Points agents to /llms.txt in a comment
• Sets Sitemap: [store_url]/sitemap.xml

Placeholders: [store_url], [store_name].

Do not add separate AI bot blocks with only Allow: / — those would bypass the SEO Disallows.

security.txt

Enable security.txt is off by default. Turn it on to publish vulnerability-reporting details at /.well-known/security.txt per RFC 9116.

Recommended starting content (placeholders filled per storefront):

Contact: mailto:security@[host]
Expires: [expires]
Preferred-Languages: en, ar
Canonical: https://[host][current_path]/.well-known/security.txt

Token	Replaced with
[host]	Storefront host
[current_path]	Install path (empty on the domain root)
[expires]	UTC date about 364 days ahead
[store_url]	Storefront home page

Replace Contact with a real security mailbox when you have one. Add optional RFC fields (Policy, Acknowledgments, Hiring) only when those pages exist. Do not add Encryption unless you publish a real public key URL.

The response is text/plain; charset=utf-8. In virtual mode nothing is written to disk. In writable mode the body is stored as security_st{storefront_id}.txt while the public URL stays /.well-known/security.txt.

Asset Links

Enable Asset Links is off by default. Use this tab for Android Digital Asset Links at /.well-known/assetlinks.json.

When enabled, the add-on serves the Asset Links JSON for the current storefront at /.well-known/assetlinks.json. In writable mode it is stored as assetlinks_st{storefront_id}.json. When disabled, that feature’s files are removed (writable mode) or the virtual URL returns not found.

Replace the sample package_name and sha256_cert_fingerprints with your Android app values before enabling. The response is application/json; charset=utf-8.

AI catalog

Agentic Resource Discovery is how an AI client finds this storefront before it opens a page or calls a tool. The add-on publishes the same document at /.well-known/ard.json and /.well-known/ai-catalog.json. It does not run those resources. Each entry points at a URL the client opens on its own.

Public pages also include <link rel="ard">, <link rel="ai-catalog">, and the same catalog as JSON-LD.

These fields are published on every entry:

• Catalog display name
• Catalog description
• Representative queries — one customer question per line. The storefront publishes two to five questions.
• Capabilities — one short token per line, such as SearchCatalog, BrowseStore, and ViewCart.
• Tags — one tag per line, such as ecommerce.

The catalog lists the llms.txt summary. Its type is text/markdown; profile="urn:air:agent-skills", which is a discovery type Lighthouse accepts. The document root includes specVersion 1.0. [store_name] works in these fields as well.

WebMCP

• Search tool name — letters, numbers, and underscores, starting with a letter. Default: search_products.
• Search tool description — what product search does.
• Form tool description — sentence added to public forms the add-on can expose.

The search tool input is JSON Schema draft 2020-12. The add-on checks it before the page registers the tool, and publishes the same document at https://your-domain/.well-known/search-products.schema.json. The AI catalog is checked the same way before it is sent. A full list of JSON Schema validators is on the JSON Schema tooling page.

Schema markup

This block is optional. Enable Schema.org markup is on by default. Turn it off for a storefront that should keep the existing structured data only.

When it is on, public pages include structured data for:

• Organization — store name, description, logo, and the company phone, email, and address already saved under Settings → Company
• WebSite — the same name, plus a site search action

Fields:

• Organization name — supports [store_name]
• Organization description
• Logo URL — leave empty to use the theme logo
• Extra JSON-LD — optional. Paste raw Schema.org JSON here (see examples below). The add-on merges it into the same application/ld+json graph as Organization and WebSite.

Each storefront can save its own values. Product pages from the CS-Cart SEO add-on are also normalized: availability uses a full https://schema.org/InStock URL, and empty product fields are left out.

Check a page with the Rich Results Test or the Schema Markup Validator.

How to add Extra JSON-LD

1. Open Add-ons → Manage add-ons → Agentic Browsing.
2. Keep Enable Schema.org markup checked.
3. Paste JSON into Extra JSON-LD (one object, or an array of objects).
4. Save, then view the storefront page source and search for application/ld+json.

Rules:

• Paste JSON only — do not wrap it in <script type="application/ld+json">...</script>.
• Every object must include "@type" (for example "Store", "LocalBusiness", "FAQPage").
• You may omit "@context"; the add-on already sets Schema.org on the page graph and strips a nested @context if you paste one.
• Invalid JSON is skipped (the built-in Organization / WebSite blocks still publish).
• Placeholders work inside string values: [store_name], [store_url], [catalog_url], [cart_url], [account_url], [contact_url], [host].

Example 1 — one object (Store)

Copy this into Extra JSON-LD:

{
  "@type": "Store",
  "name": "[store_name]",
  "url": "[store_url]",
  "image": "https://[host]/images/logos/store.png",
  "priceRange": "$$",
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": [
        "Monday",
        "Tuesday",
        "Wednesday",
        "Thursday",
        "Friday"
      ],
      "opens": "09:00",
      "closes": "18:00"
    }
  ]
}

Example 2 — several objects (array)

Use a JSON array when you need more than one extra type:

[
  {
    "@type": "Store",
    "name": "[store_name]",
    "url": "[store_url]",
    "priceRange": "$$"
  },
  {
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "How do I track my order?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Sign in at [account_url] and open your orders."
        }
      },
      {
        "@type": "Question",
        "name": "Where is the product catalog?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Browse products at [catalog_url]."
        }
      }
    ]
  }
]

After save, the page JSON-LD graph looks like: Organization + WebSite (from the add-on) plus your Extra objects. Do not paste a second Organization unless you intentionally want a duplicate type.

Accessibility for agents

This block follows the Accessibility for agents check. Agents read the accessibility tree, so a button or link that is only an icon needs a name.

Enable accessibility for agents is on by default. Turn it off for a storefront that should keep the theme markup unchanged.

The add-on does not replace labels that are already present. It adds a name only when a button, link, or field has none. Default accessible names is one line per name:

search: Search
cart: Cart
account: Account
menu: Menu
close: Close
wishlist: Wishlist
button: Action
link: Link
field: Input

search, cart, account, menu, close, and wishlist are chosen from the control’s class or link. Other buttons use button, other links use link, and other fields use field. [store_name] works in these lines. Each storefront can save its own list.

Different text per storefront

When the installation has more than one storefront:

1. Open Agentic Browsing settings.
2. Select the storefront.
3. Edit llms.txt markdown, robots.txt, security.txt, Asset Links JSON, the catalog fields, the WebMCP text, the schema fields, or the accessible names.
4. Save.

That storefront keeps its own copy. Other storefronts keep the default, or their own saved text. https://store-one.example/llms.txt and https://store-two.example/llms.txt can therefore differ while both domains use the same CS-Cart installation.

.well-known serving mode on General is ROOT-wide (not per storefront). In writable mode, each storefront’s body is stored as security_st{ID}.txt / ard_st{ID}.json / … while every domain still exposes the standard public path (/.well-known/security.txt, /.well-known/ard.json, and so on).

Verify

1. Confirm {CS-Cart root}/robots.txt and {CS-Cart root}/llms.txt do not exist as static files.
2. With Virtual mode: confirm the root .well-known folder has no add-on discovery files (or is removed), confirm the vhost passes /.well-known/* to PHP, then open /.well-known/ard.json.
3. With Enable security.txt on, open https://{domain}/.well-known/security.txt.
4. With Enable Asset Links on, open https://{domain}/.well-known/assetlinks.json.
5. Optionally switch to Writable, save, and confirm *_st{ID}.* files exist while public URLs stay the same.
6. Reload a storefront page and confirm the page source contains rel="ard", rel="ai-catalog", and application/ld+json.