The README describes a2ml-showcase as a content-only repository of examples and templates for the A2ML (Attested Markup Language) format. This file traces the content structure, identifies the critical documentation paths, and records how the showcase fits into the wider A2ML ecosystem.
This repository contains example A2ML documents, templates, and rendered output demonstrating the capabilities of the A2ML format. It is a content/showcase repository — there is no executable code.
How it works. A2ML is a structured identity and attestation format for
software agents. An .a2ml file combines human-readable markup (headings,
paragraphs, lists) with machine-verifiable directive blocks delimited by
@<directive>: … @end. The mandatory directives are @abstract: (a
human-readable description) and @attestation: (a structured block carrying
agent-id, attested-by, trust-level, capabilities, and scope).
The content/ directory holds five Markdown documentation pages rendered to
HTML via template.html:
-
index.md— format overview, feature grid (attestation chains, provenance tracking, agent identity, CI/CD native), and the "why A2ML" narrative. -
getting-started.md— minimal manifest walkthrough. -
examples.md— three worked examples: minimal self-declared bot, CI/CD agent with verified attestation, and a multi-agent orchestration manifest. -
integrations.md— tooling ecosystem coverage. -
specification.md— format reference (directives, trust levels, grammar).
The examples.md content demonstrates that even the simplest valid A2ML file
(a greeter bot with a @attestation: block declaring trust-level:
self-declared) is enough for tooling to identify the agent and record its
claims. The CI/CD agent example shows a verified attestation where a security
team countersigns the capabilities block, lifting trust-level from
self-declared to verified.
Honest caveat. a2ml-showcase is documentation, not a parser. The .a2ml
snippets in content/examples.md are illustrative; their correctness against
the A2ML grammar is not enforced by a running parser in this repo. The
grammar and parser live in tree-sitter-a2ml; the normative specification
lives in standards.
Critical path. content/index.md → explains attestation chain model →
content/examples.md → minimal, CI/CD, and multi-agent worked examples →
output/examples.html (rendered via template.html) → read by tooling
authors and agent developers.
A2ML is not a paper specification. It ships with real, working tools: Pandoc reader, writer, filter, and template via pandoc-a2ml; VS Code syntax highlighting via vscode-a2ml; Tree-sitter grammar via tree-sitter-a2ml; GitHub Linguist language detection (submission pending).
How it works. content/integrations.md is the canonical cross-reference for
this claim. It links: pandoc-a2ml (convert A2ML to HTML, PDF, Markdown, 40+
formats); vscode-a2ml (syntax highlighting in VS Code); tree-sitter-a2ml
(Neovim, Helix, Zed, GitHub); and format-registrations (IANA media type
application/vnd.a2ml, freedesktop.org MIME XML, Wikidata entity). The
showcase also references that 0-AI-MANIFEST.a2ml files are recognised by
glob patterns 0-AI-MANIFEST.a2ml and AI.a2ml at weight 60 in the
shared-mime-info XML — giving file managers and editors first-class detection.
Honest caveat. The GitHub Linguist submission is described as "pending". The VS Code extension is published but not yet widely known. Pandoc integration is the most mature path.
Critical path. content/integrations.md → links to pandoc-a2ml →
pandoc --from a2ml --to html converts A2ML to HTML → output is
indistinguishable from hand-written HTML but with attestation metadata
preserved in <meta> tags.
deno test --allow-read tests/The test suite in tests/validate.test.ts checks:
-
All five
content/*.mdfiles exist. -
output/directory exists and contains rendered artefacts. -
template.htmlis present and non-empty. -
tests/fuzz/contains a fuzz corpus (directory exists check). -
Spot-checks that
content/index.mdcontains the A2ML identifier and at least one@attestationreference.
tests/fuzz/ holds a fuzz corpus for property-based testing against unusual
document structures.
| Consumer | How it uses this repo |
|---|---|
|
The normative A2ML specification in |
|
|
|
Uses the directive examples from |
|
rhodibot’s own |
Every hyperpolymath repo |
All repos carry a |
|
Hypatia’s A2ML manifest validation rule checks that |
| Path | What’s There |
|---|---|
|
A2ML format overview. Covers: attestation chains, provenance tracking, agent identity, CI/CD native design. The feature grid and "Why A2ML?" narrative. |
|
Minimal manifest walkthrough. Shows the simplest valid |
|
Three worked examples: (1) minimal self-declared greeter bot; (2) CI/CD
agent with security-team countersignature; (3) multi-agent orchestration
manifest with cross-agent |
|
Tooling ecosystem: pandoc-a2ml, vscode-a2ml, tree-sitter-a2ml, format registrations, GitHub Linguist. Status notes for each. |
|
Format reference: directive grammar, trust levels ( |
|
Rendered HTML pages (generated from |
|
HTML rendering template. Used by the build step to convert |
|
One-screen overview: what A2ML is, content structure, licence. |
|
Deno test suite. File existence, content structure, template presence, and fuzz corpus checks. |
|
Fuzz corpus for property-based edge-case testing. |
|
|
|
Deno runtime config and lockfile. |
|
Reproducible build environment declarations. |
|
Stapeln container configuration for this repo. |
|
Contractile recipe stubs (RSR standard). |
|
AI agent manifest for this repo — itself an example of the format it documents. |
Open an issue on GitHub or reach out to Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> — happy to explain anything in more detail.