// SPDX-License-Identifier: CC-BY-SA-4.0
= A2ML (Attested Markup Language)
:toc: preamble
:toclevels: 2
:icons: font

A2ML is a lightweight, Djot-like markup that compiles into a typed, attested core.
It keeps authoring simple while allowing strong structural guarantees when you
want them.

This repository is a satellite of the Hyperpolymath standards hub.

== What It Does

* Author a readable surface format with strict, typed guarantees when needed.
* Validate structure (IDs, refs, required sections) with progressive modes.
* Preserve opaque payloads byte-for-byte for reliable embedding.

== Where It Is Going

* Broader tooling integration (CLI, LSP, renderers).
* More profiles for domain-specific validation.
* Stronger proof coverage and conformance automation.

== Why A2ML

* Lightweight authoring with progressive strictness (lax -> checked -> attested)
* Strong guarantees: required sections, resolved references, unique IDs
* Opaque payloads preserved byte-for-byte for absolute fidelity
* Renderer portability across HTML/Markdown/PDF pipelines

== Quick Start (Module 0)

[source,a2ml]
----
# A2ML Overview

@abstract:
A2ML is a typed, attested markup format. It verifies structure and references.
@end

## Claims
- Required sections must exist.
- References must resolve.

@refs:
[1] Attested Markup Language Spec (draft)
@end
----

== Documents

* link:SPEC.adoc[Spec (current normative, v1.1.0): Surface Grammar + Typed Core + Profiles]
* link:VERSIONS.adoc[Specification Lineage (versions + era)]
* link:archive/[Archived (frozen) prior specs]
* link:docs/QUICKSTART.adoc[Module 0 Quickstart + FAQ]
* link:docs/MODULES.adoc[Syntax Modules (Opt-in)]
* link:docs/GRAMMAR.adoc[Grammar Appendix]
* link:docs/CONFORMANCE.adoc[Conformance + Test Vectors]
* link:docs/CONFORMANCE-PLAN-v1.adoc[v1 Conformance Plan]
* link:docs/WEB-RENDERING.adoc[Web Rendering Options]
* link:docs/IANA-MEDIA-TYPE.adoc[IANA Media Type Draft]
* link:docs/COMPARISON.adoc[Comparison Matrix]
* link:docs/CITATIONS.adoc[Citation Guide]
* link:docs/demo.html[Demo (HTML)]

== Prototype

* link:prototype/rescript/README.adoc[ReScript Web Prototype]
* link:prototype/wasm/README.adoc[ReScript + WASM Prototype]
* link:prototype/ddraig/DemoBuild.idr[ddraig-ssg demo build]

== Idris2 Core

* link:src/A2ML/TypedCore.idr[Typed core stub]
* link:src/A2ML/Translator.idr[Translation stub]
* link:src/A2ML/Surface.idr[Surface AST]
* link:docs/AST-JSON.adoc[Surface AST JSON (prototype)]
* link:docs/DIRECTIVE-MAPPING.adoc[Directive Mapping (prototype)]
* link:docs/INLINE-RULES.adoc[Inline Rules (prototype)]

== Vectors

* link:docs/VECTORS.adoc[Vector Runner (Prototype)]

== Core Tests

* `just core-tests` (Idris2)

== CLI

* link:docs/CLI.adoc[CLI (prototype)]
* link:docs/a2ml.1[Man page]
* link:docs/PACKAGING.adoc[Packaging notes]
* `just package-cli`

== Ada/SPARK TUI

* link:prototype/ada-tui/docs/README.adoc[Ada/SPARK TUI (prototype)]

== Release Notes

* link:RELEASE-NOTES-v0.1.0.adoc[v0.1.0 Release Notes]
* link:RELEASE-NOTES-v0.5.0.adoc[v0.5.0 Release Notes]
* link:RELEASE-NOTES-v0.6.0.adoc[v0.6.0 Release Notes]
* link:RELEASE-NOTES-v1.0.0.adoc[v1.0.0 Release Notes]
* link:RELEASE-NOTES-v1.1.0.adoc[v1.1.0 Release Notes]

== Announcement

* link:docs/ANNOUNCEMENT.adoc[Announcement Draft]
* link:docs/STATE-OF-A2ML.adoc[State of A2ML]
* link:docs/V1-CRITERIA.adoc[v1.0.0 Criteria]

== Status

* *Stable specification, v1.1.0* (era v1). See link:VERSIONS.adoc[VERSIONS.adoc]
  for the lineage; prior drafts (v0) and the frozen v1.0.0 release are under
  link:archive/[archive/].
* v1.1.0 is additive over v1.0.0: profile mechanism, base record vocabulary,
  citation primitives, and canonical hashing — all inert under the base modes.
* Prototype parser + CLI + demo page available.
* Typed core + core tests passing (prototype).

== License

PMPL-1.0-or-later. See link:LICENSE[LICENSE].
