Concepts and glossary

Sill sits between AI agents and your store and answers three questions about every agent interaction: who is visiting (identity), what it is trying to do (intent), and what record remains (proof). This page defines the terms the rest of the docs use.

How the pieces work together

flowchart LR
  A[AI agent] -->|reads| B[Your agent card]
  A -->|sends a signed order| C[Your guardrails]
  C -->|approve| D[Stripe charges the card]
  C -->|hold| E[You review it]
  E -->|approve| D
  C -->|reject| F[Order refused]
  D --> G[Signed audit record]
  E -->|reject| F
  F --> G

In Discovery mode only the left part happens: Sill identifies the agent and writes a signed record of the visit. There is no order, no policy check and no payment.

Account

Your company’s workspace in Sill. An account holds your sites and your users. Data is stored in the US.

Site

One domain you added to Sill, such as northwind-coffee.example. A site is the unit you install, verify and configure: each site has its own site key, skills, guardrails and audit log. A subdomain such as shop.northwind-coffee.example is a separate site.

The site key (shaped us_…) identifies your site in the install snippet and in the URLs of your agent card and MCP server. It is meant to be public, like a Stripe publishable key.

A site is in one of these states:

State	Meaning
`pending_proof`	Added, but domain ownership is not verified yet. Sill publishes nothing for it.
`discovery_active`	Verified. Sill records agent visits and publishes the agent card, MCP server and ARD catalog.
`transactional_active`	Verified and connected to a store or payment platform for agent orders.
`suspended`	Turned off by Sill support.

See Sites and onboarding and Domain verification.

Skill

Something agents can do on your store. Sill has seven default skills:

Skill	What it lets an agent do
`browse_catalog`	Search and browse your products.
`check_availability`	Check stock.
`place_order`	Place an order (needs a signed mandate and a payment connection).
`order_status`	Look up an order.
`track_shipment`	Track an order’s shipment.
`request_refund`	Ask for a refund (needs a signed mandate).
`recommend`	Get product recommendations.

A skill is advertised to agents only when something can actually carry it out, such as a connected store. You can also add your own custom skills. See Skills.

Agent

A non-human visitor: an AI assistant, an AI crawler or a search bot. Sill keeps a registry of known agents (from Anthropic, OpenAI, Google, Perplexity, Microsoft, Meta and others) and matches each visit against it. Agents do not need a Sill account. To send orders in Transactional mode, an agent registers a public key so Sill can check its signatures. See Identifying agents.

Agent card

A signed JSON file Sill publishes for each verified site at https://edge.sill.so/v1/agent-card/{site_key}.json. It tells agents who you are, which skills your store offers and where your MCP server is. It is compatible with the A2A agent card format, and anyone can check its signature. See Agent card.

Mandate

A signed request from an agent to do something on your store, such as place an order up to a set amount. The agent signs it with its registered key, so Sill can tell who sent it and that nobody changed it on the way. Mandates are the core of Transactional mode. See Signed mandates.

Policy and rule

Your policy is the set of rules for a site: an ordered list of rules. Each site has one active policy. When you publish changes, Sill saves a new version, and each audit record notes the policy version it was checked against.

A rule is one guardrail, such as “cap any single order at $500” or “only these agents may order”. When a rule fires it does one of three things:

Reject — refuse the order.
Escalate — hold the order for a person to approve or reject in Held orders.
Allow — approve it straight away and skip the remaining rules (an exemption).

Rules run in order; the first rule that fires decides. If none fires, the order is approved. See Policy engine for the rule list.

Audit record

The signed record Sill writes for every agent visit (Discovery) and every decision on a mandate (Transactional). Records are append-only and chained together, so a removed or altered record is detectable. You can export them as a signed bundle and anyone can verify it. See Audit log and bundle export and Audit envelope.

The decision on a record is one of:

Decision	Meaning
`observed`	An agent visit (Discovery). No order involved.
`approved`	The order passed your guardrails.
`rejected`	A rule rejected the order.
`escalated_approved` / `escalated_rejected`	A rule held the order and a person approved or rejected it.
`verification_rejected`	The mandate’s signature or timing was invalid, so it never reached your guardrails.
`rejected_post_verify`	The same mandate was sent twice; only the first one counts.
`settled_succeeded` / `settled_refunded`	A follow-up record when the payment settled, or was refunded.
`handoff_pending`	A follow-up record when a WooCommerce order was created with a payment link and is waiting for payment.

User and roles

A person who signs in to your account. Sill uses email sign-in links; there are no passwords.

Role	Can do
`owner`	Everything, including deleting the account.
`admin`	Configure sites and manage users.
`reviewer`	See held orders and all records, but not approve or reject them.
`viewer`	Read only.

A user is invited, active, suspended or deactivated. See Users and roles.

Principal

The person or organization an agent acts for, carried inside the mandate: human, organization, or none when the agent acts on its own. Rules that cap spend per customer use it, through a one-way hashed reference rather than the customer’s email or name.

Common questions

Can two sites in one account have different guardrails? Yes. Each site has its own policy.

Do agents need a Sill account? No. Sill identifies visiting agents itself. Only agents that send signed orders register a public key.

Where do I check a Sill signature? Use the public key set at https://edge.sill.so/.well-known/jwks.json and follow Verify a signature. For exported audit bundles, drop the file on sill.so/verify.