Let every store speak for itself

Why this exists

Ask an AI assistant about a store. Does this ship to me, what does the warranty actually cover, which of these fits the bike I already own? Today it answers by guessing from whatever pages it managed to scrape, and when it guesses wrong, everyone loses quietly: the shopper acts on a warranty that says something else, the store is misrepresented or simply invisible, and the web drifts a little further toward being written for crawlers instead of people.

The remedy is old-fashioned: let the store say what is true, plainly, in a place where anyone can look. OKF-Web builds that place. It is a folder of readable files on your own website, one file per fact worth standing behind. Each file names the person who checked it, carries a fingerprint that makes tampering visible, and can be signed so anyone can verify who published it, even from a copy. No registry, no gatekeeper, no fee to be found.

Infrastructure for trust should not be owned. This toolchain is free and open source, Apache-2.0 now and always; the hosted edition exists to fund the commons, never to fence it.

One thing said early, because candor is the point: OKF is a real, published format, the shopping-specific layer on top of it is this project's own, and no AI engine fetches OKF bundles yet. The toolchain is built to be worth using anyway. It also produces the machine-readable summaries that search and AI tools already read today, and it measures what an assistant can actually answer about your store, so the work pays for itself before any bet on the future does.

How it works

• Gather. Your product feed and policy pages become draft

knowledge files. Numbers that change by the hour, like prices and stock, are never copied into the text; readers fetch them live from the store, so nothing published can quietly go stale.

• Verify. A person reads and signs. The label human-reviewed

means someone read that file; human-attested means a named person signed off on a batch; a machine never wears either label.

• Publish. The bundle ships with a contents list that

fingerprints every file, plus the standard machine-readable summaries (schema.org markup and an llms.txt index) restating only what humans vouched for.

• Measure. A set of shopper questions, the kind real buyers ask,

is put to the bundle and graded, so coverage is a number you can watch and the gaps are a to-do list rather than a mystery.

• Keep it true. Routine checks re-read your sources and flag

changes for a person to approve. Verified content is never silently rewritten.

Ten minutes, no credentials

pip install okf-web
okf-web init my-store          # feed → drafts → attest → questions →
                               # scorecard → publish → report, guided
okf-web report my-store        # the shareable answerability report

The guided first run needs no AI account at all: it reads your product feed, walks you through approving what it drafted, asks a starter set of shopper questions, and leaves you a measured scorecard and a publishable bundle.

When you want the full, AI-written evaluation, bring whichever Claude access you already have. --llm api uses an API key or a keyless login profile and bills per use; it is the right path for anything scheduled or unattended. --llm claude-code runs through the Claude subscription you may already pay for, via the claude command-line app you log into once, with no API key and nothing extra to buy; it is meant for runs you sit with. The toolchain treats both as equals.

Measured on the reference store

New words for an old promise are easy, so the toolchain ships with its own proof: a complete example store, the *reference store*, whose bundle is evaluated the way a shopper would use it. The evaluator asks the questions real buyers ask, checks whether the right knowledge was found and whether it actually answered, and compares the whole exercise against scraping the same store's raw pages. These are those measurements:

Measured by the open evaluator on the reference bundle, the complete example store that ships with the toolchain, and re-read from its recorded scorecard at every build. No number here is typed by hand; run okf-web evaluate on your own bundle for yours.

Nothing above is a claim about your store. It is what the method achieves on a store built with it, and okf-web evaluate produces the same numbers for yours.

What the toolchain holds firm

• Changing numbers stay live. Prices, stock, and delivery times

are never stored as text claims; they ship as live lookups the store controls, and the feed importer refuses to copy them in.

• Named humans, honest labels. human-reviewed means a person

read it; human-attested means a named person signed off on a batch; machines never wear either label.

• Verifiable by construction. Every published file is

fingerprinted, publications can be signed and countersigned, and an automatic checker must pass clean before anything deploys.

• Useful with zero engine adoption. The standard summaries it

produces work with today's search and AI tools; the bundle is the upside on top, not the price of admission.

For AI assistants

Assistants are first-class here in two roles, and the toolchain holds the line between them.

As readers: any assistant that can use tools (the MCP standard) can query a published store directly through the bundled server:

okf-web mcp bundle-example     # stdio server: okf_search / okf_get /
                               # okf_execute (GET-only, token-scoped)

It can search the knowledge, read any file, see which live lookups the store offers, and run them. That server is read-only on purpose: publishing a bundle opens a window into the store, never a door, so no assistant can be talked into placing an order or changing a record through it.

As operators: the process itself is built to be run by an assistant working alongside you. Every step is a plain command over plain files, so an assistant that can run commands, Claude Code for one, can manage the whole cycle: gather your feed and pages into drafts, queue them for your review, check the bundle, measure it, publish it, and watch for changes at the sources. The one step that never leaves your hands is the sign-off on what is true. The --llm claude-code path above is the same idea from the other side: the assistant subscription you already have can also power the evaluation.

This site also publishes its own bundle at /.well-known/okf/ and an llms.txt index. Assistants are first-class readers here, not scraped traffic.

The hosted option

If you'd rather this were run for you, a hosted edition exists: the same open machinery operated by careful hands, with monitoring that keeps your bundle verified and current, audits when you want the deep look, and a store-platform connection whose serving fees begin only if AI engines demonstrably read your bundle. The open tools are complete, and running them yourself will always be a first-class path. Leaving the hosted service is one command, taking everything with you costs nothing, and both of those are tested, not promised.