Token of Trust — Storefront Devkit

Runnable starting points, schemas, and examples for building high-performance, regulated ecommerce storefronts on the Token of Trust (ToT) Storefront platform.

This repo is the companion to the ToT Storefront devbooks (the task-by-task how-to guides served over the ToT MCP). The devbooks teach you how; this repo gives you runnable files — fork a starter, copy a snippet, validate against a schema, ship.

You do not need access to the platform source code to use anything here. Everything in this repo is tenant-side: the exact files you author (theme.json, content/*.json, scripts.json, public/**) and the machine-checkable schemas that describe them. Nothing here reveals platform internals.

---

Quick start (humans)

# 1. Try the platform with zero setup — offline, no login:
npx @tokenoftrust/cli dev --sample

# 2. Start a real client project from a template:
#    (on GitHub, click "Use this template"; or copy a folder)
cp -R templates/commerce-minimal ../my-client-store
cd ../my-client-store

# 3. Point your editor at the schemas for autocomplete + validation
#    (already wired in .vscode/settings.json — copy it into your project)

# 4. Edit theme.json / content/*.json, then run the local loop:
tot dev            # http://localhost:<port>/<tenant>/  — save → live-reload

# 5. Validate against the contract before you publish:
tot validate

New here? Read the storefront-devbook-index devbook first (search scope:storefront genre:devbook on the ToT MCP) — it gives you the mental model. Then come back and start from a template.

Quick start (coding agents / LLMs)

Read these three files, in order, before doing anything:

1. AGENTS.md — how to use this repo and the non-negotiable customization contract (the "golden rules" the platform enforces).
2. manifest.json — the machine catalog of every asset (id, kind, path, description, tags, contract version). Locate assets here instead of crawling directories.
3. llms.txt — a curated link index (llmstxt.org convention) to the schemas, templates, and devbooks.

Then: pick a template, load the matching JSON Schema from schemas/, and make the smallest contract-valid change. Always run tot validate and report the result.

---

How this repo is organized

The organizing principles (why it looks like this):

• Two front doors, one catalog. Humans enter through README.md; machines enter through AGENTS.md + manifest.json + llms.txt. Both resolve to the same assets — no divergence.
• One asset = one self-contained directory with its own README.md and a small meta.json. To grow the repo you add a directory; you never restructure. manifest.json is generated by aggregating every meta.json.
• Schemas are the source of truth for shape. Every tenant-owned file type has a JSON Schema. Templates and snippets validate against them in CI, editors autocomplete from them, and agents check against them. If the contract is ambiguous, the schema wins.
• Everything is tenant-side and source-free. Every file mirrors what you author for a real tenant. Nothing here needs — or exposes — platform source.
• Versioned to the contract. Assets declare which contract they target (e.g. block-palette@3) in their meta.json, so you can pin to what your tenant supports.

storefront-devkit/
├── README.md              ← you are here (human entry point)
├── AGENTS.md              ← LLM/agent entry point + the customization contract
├── llms.txt               ← machine link index (llmstxt.org)
├── manifest.json          ← machine catalog of every asset (generated from meta.json files)
├── CONTRIBUTING.md        ← conventions: how to add an asset, naming, versioning
├── CHANGELOG.md
├── .vscode/settings.json  ← wires the schemas to your tenant files (autocomplete + validation)
│
├── schemas/               ← JSON Schemas for every tenant-owned file (the contract, machine-checkable)
│   ├── theme.schema.json
│   ├── chrome.schema.json
│   ├── home.schema.json           (block-palette@3)
│   ├── scripts.schema.json
│   ├── capabilities.schema.json
│   ├── compliance.schema.json
│   └── tot-config.schema.json
│
├── templates/             ← forkable starter tenants ("Use this template")
│   ├── commerce-minimal/          a clean commerce store
│   ├── marketing-minimal/         a marketing/landing site
│   └── regulated-vape/            a compliant, age-restricted store
│
├── snippets/              ← copy-paste fragments, one concern each
│   ├── blocks/                    one file per homepage block
│   ├── chrome/                    mega-menu, footer patterns
│   ├── compliance/                each compliance widget config
│   ├── product-sources/           each product-source form
│   └── theme-presets/             ready-made palettes + type pairings + brand-alias block
│
├── widgets/               ← sandboxed widget examples (correct slot/strategy/isolation)
│   └── loyalty-signup/            (more to come)
│
├── recipes/               ← end-to-end task cookbook (README + exact file diffs)
│   ├── enable-pact-compliance/
│   └── add-subscription-option/
│
├── ci/                    ← pre-submit gate you run in your own workflow
│   └── github-actions/validate.yml
│
├── agent-kit/             ← drop-ins for the agency's own repo (AGENTS.md template, prompts)
│
├── migration/             ← porting an existing store (website_* MCP flows + visual-parity template)
│
├── private-apps/          ← SECOND TRACK: connect your own service via the private-app contract (links to canonical sources)
│
├── industries/            ← by-vertical guides (vape, alcohol, hemp/CBD, firearms, marketplaces)
│
├── docs/                  ← repo meta: DISCOVERABILITY.md (SEO / how the repo gets found)
│
└── site/                  ← optional GitHub Pages landing (robots.txt, sitemap.xml, index.html) — inert until Pages is enabled

The directories in one line each

Directory	Use it when you want to…
schemas/	Validate a tenant file, or wire editor autocomplete
templates/	Start a new client project from a clean, contract-valid base
snippets/	Drop one block / widget config / theme preset into an existing store
widgets/	Add sandboxed interactivity the right way
recipes/	Follow a complete, worked task end-to-end
ci/	Gate your team's PRs on tot validate before submitting
agent-kit/	Make your own coding agent obey the customization contract
migration/	Port a client's existing store onto the platform
private-apps/	Connect your own backend service to a store (the app-developer track)
industries/	Build for a specific regulated vertical (vape, alcohol, hemp/CBD, firearms, marketplaces)
docs/	Understand how the repo gets found (SEO / discoverability checklist)
site/	Publish a searchable landing page via GitHub Pages (optional)

The contract in six rules (full detail in AGENTS.md)

1. Edit only tenant-owned files — never platform code.
2. Never fabricate compliance facts or legal copy; never disable/hide required compliance UI.
3. No raw HTML, inline scripts, onclick=, or javascript: URLs for regulated tenants.
4. Checkout & subscriptions are platform-owned — use managed checkout + the purchase_options shape.
5. Prefer data + tokens over anything that looks like code.
6. Escalate, don't smuggle: sandboxed widget → private app → single-tenant extraction.

Versioning & compatibility

• Assets declare the contract they target in meta.json ("contract": "block-palette@3").
• The CLI (@tokenoftrust/cli) and runner ship on npm; pull the latest for new blocks/features.
• Breaking contract changes get a new schema version; old templates keep validating against the version they pin. See CONTRIBUTING.md.

About the Token of Trust Storefront platform

Token of Trust Storefront is a commerce platform built for regulated ecommerce — the categories mainstream platforms deplatform (vape & nicotine, wine & spirits, hemp & CBD, firearms, and more). Its differentiators:

• Compliance is native and can't be turned off — age/ID verification, PACT Act, and excise tax are part of the platform, so you're never one policy change away from a shutdown.
• Own your exit — leave any time with a clean, runnable copy of your code, brand, content, and catalog. No lock-in.
• Agent-native dev loop — build with an AI coding agent in a local loop, with a compliance gate that prevents a non-compliant store from ever going live.

It's backed by the Token of Trust verification & compliance suite: Government ID Verification, Biometric Face Verification, Age Verification / Age Estimation / Age Gate, eCommerce Fraud Prevention, Anti-Money Laundering (AML), PACT Act Compliance, and Sales / Use / VAT / Excise Tax.

• Platform & early access → storefront.tokenoftrust.store
• Verification & compliance products → tokenoftrust.com
• Build by industry → industries/
• Docs → help.tokenoftrust.com

License & contributions

Licensed under Apache License 2.0 (see LICENSE) — a permissive license (with an explicit patent grant and trademark disclaimer) covering the devkit's example templates, schemas, snippets, sample code, and docs, which you may freely use (including commercially) to build storefronts. Important: this license does not cover the Token of Trust Storefront platform itself (the renderer runtime, @tot/public-runtime, and @tokenoftrust/storefront-runner), which is licensed separately under the Token of Trust Source-Available License — Local Development Only. See NOTICE for the scope boundary and trademark terms.

Community contributions welcome via PR (merge-gated). See CONTRIBUTING.md for the one-asset-per-directory convention and the meta.json schema. Nothing platform-internal is ever accepted here — this repo stays strictly tenant-side.