ajar-examples - Demo Sites and Reference Scenarios

Small Next.js sites that implement Ajar directly. They show how agents read and act through the protocol, and they publish the measured token, latency, and accuracy results.

Status: specs-only (docs). Built during Phases 1–3 alongside the pieces they demonstrate. Each demo lives in a subfolder here (or graduates to its own repo when it stabilizes).

---

Demo 1 - docs-site: documentation without HTML parsing

ajarprotocol.org will run this demo.

What it is: a Next.js documentation site using the Ajar spec/docs as content. It implements Profile CORE natively, without a Gateway:

• Route handler for /.well-known/ajar.json with a signed manifest. This is the pattern ajar-docs-mcp teaches through scaffold_guidance("nextjs").
• Content negotiation in middleware: browsers get the normal docs UI; Accept: application/ajar+json gets chunked semantic views generated at build time from the same MDX source.
• Stable chunk IDs from MDX heading slugs; per-chunk hashes; view index for diff sync; search_docs declared as a free R0 action.
• License block: read=allowed, train=denied.

Experiment: answer the same 10 documentation questions with the same agent three ways: raw HTML fetching, markdown negotiation only, and full Ajar (manifest, view index, chunk diffs, and search action). Report tokens, latency, answer accuracy, and cost. Target: 10-20% of raw-HTML tokens with equal or better accuracy.

Also show a returning agent syncing after a docs edit and fetching only changed chunks.

Demo 2 - storefront: sandbox commerce

What it is: a Next.js e-commerce demo with a fake catalog and sandbox payments, implementing CORE + ACT natively:

• Products as views; search_catalog (R0), add_to_cart (R1, idempotent), checkout (R3).
• SIMULATE path: agent simulates checkout -> exact landed cost and refund terms returned -> Kernel checks the result against a demo mandate ("<= $150, this week") -> propose -> signed offer with a 10-minute freeze -> commit -> dual-signed receipt shown on screen.
• Failure paths: over-mandate cart blocked by the Kernel with the arithmetic shown; expired offer refused at commit; planted prompt injection in a product description logged and blocked.

Demo 3 - blog-minimal: one-hour CORE setup

A small Next.js blog gaining CORE with a few dozen lines of route and middleware config. This is the fixture for get_checklist("nextjs-site").

Shared harness

agent-runner/: a small script that drives a Kernel-wrapped agent through each demo scenario and produces metrics tables plus artifact bundles (mandates, offers, receipts). These bundles feed ajar/examples/, and the scenarios feed conformance acceptance tests.

Build order & DoD

1. docs-site (Phase 1-2: needs CORE spec + Kernel read path). DoD: experiment table published; site passes conformance CORE; deployed as ajarprotocol.org.
2. blog-minimal (same phase, days of work). DoD: documented diff from create-next-app to conformant, under one screen of changes.
3. storefront (Phase 3: needs ACT). DoD: full simulate -> commit -> receipt flow plus all three failure cases recorded; conformance ACT green.

Rules

Demos are normative consumers. If a demo needs something the spec does not provide, file an AEP instead of adding a private workaround. Demos use only the protocol, not private APIs of the reference implementations. Each demo README must include current measured numbers.

License

Apache-2.0. See LICENSE.