From 207c5677c7c51f9ddd005e9203ddf86d5d074932 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 19:49:58 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 66 ------------------------------------- README.md | 93 ++++++++++++++++++++++++++++------------------------- 2 files changed, 49 insertions(+), 110 deletions(-) delete mode 100644 README.adoc diff --git a/README.adoc b/README.adoc deleted file mode 100644 index f5de34c..0000000 --- a/README.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= a2ml-rs -Jonathan D.A. Jewell -:toc: -:toc-placement: preamble - -Rust parser and renderer for A2ML (Attested Markup Language) — the -structured markup format used across the hyperpolymath estate for AI-agent -communication, machine state files, and provenance-tracked documentation. - -== Overview - -A2ML extends a Markdown-like surface syntax with two first-class constructs: - -* `@directives` — single-line machine-readable metadata prefixed with `@` -* `!attest` blocks — record identity, role, and trust-level on any piece - of content, enabling provenance tracking across AI-agent and human review chains - -`a2ml-rs` implements: - -* `src/parser.rs` — line-oriented state machine: headings, directives, - attestation blocks, fenced code, block quotes, ordered/unordered lists. - Entry points: `parse()` and `parse_file()`. -* `src/renderer.rs` — serialises a `Document` AST back to canonical A2ML, - making round-trips deterministic. -* `src/types.rs` — core types: `Document`, `Block`, `Inline`, `Directive`, - `Attestation`, `TrustLevel` (Unverified → Automated → Reviewed → Verified), - `Manifest`. -* `src/error.rs` — `A2mlError`: `ParseError`, `Io`, `RenderError`. - -The crate root is `#![forbid(unsafe_code)]`. Dependencies: `serde`/`serde_derive` -for serialisation, `thiserror` for error types, `criterion` for benchmarks only. - -== Usage - -[source,rust] ----- -use a2ml::{parse, render}; - -let doc = parse(input_str)?; -let output = render(&doc)?; ----- - -== Attestation Trust Levels - -[cols="1,3"] -|=== -| Level | Meaning - -| `Unverified` | No review — raw agent or tool output -| `Automated` | Processed by a pipeline without human review -| `Reviewed` | Human-reviewed (claimed, not cryptographically proved) -| `Verified` | Formally verified or cryptographically attested -|=== - -Attestations are syntactic declarations, not cryptographic signatures. -Signature verification belongs in the Groove protocol stack. - -== Related - -* link:https://github.com/hyperpolymath/pandoc-a2ml[pandoc-a2ml] — Pandoc reader/writer for A2ML -* link:https://github.com/hyperpolymath/a2ml-haskell[a2ml-haskell] — Haskell implementation - -== License - -MPL-2.0. See link:LICENSE[LICENSE]. diff --git a/README.md b/README.md index a1e4854..9ad08e1 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,73 @@ -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) - -// SPDX-License-Identifier: CC-BY-SA-4.0 -= a2ml-rs -Jonathan D.A. Jewell -:toc: -:toc-placement: preamble + Rust parser and renderer for A2ML (Attested Markup Language) — the -structured markup format used across the hyperpolymath estate for AI-agent -communication, machine state files, and provenance-tracked documentation. +structured markup format used across the hyperpolymath estate for +AI-agent communication, machine state files, and provenance-tracked +documentation. + +# Overview -== Overview +A2ML extends a Markdown-like surface syntax with two first-class +constructs: -A2ML extends a Markdown-like surface syntax with two first-class constructs: +- `@directives` — single-line machine-readable metadata prefixed with + `@` -* `@directives` — single-line machine-readable metadata prefixed with `@` -* `!attest` blocks — record identity, role, and trust-level on any piece - of content, enabling provenance tracking across AI-agent and human review chains +- `!attest` blocks — record identity, role, and trust-level on any piece + of content, enabling provenance tracking across AI-agent and human + review chains `a2ml-rs` implements: -* `src/parser.rs` — line-oriented state machine: headings, directives, - attestation blocks, fenced code, block quotes, ordered/unordered lists. - Entry points: `parse()` and `parse_file()`. -* `src/renderer.rs` — serialises a `Document` AST back to canonical A2ML, - making round-trips deterministic. -* `src/types.rs` — core types: `Document`, `Block`, `Inline`, `Directive`, - `Attestation`, `TrustLevel` (Unverified → Automated → Reviewed → Verified), - `Manifest`. -* `src/error.rs` — `A2mlError`: `ParseError`, `Io`, `RenderError`. +- `src/parser.rs` — line-oriented state machine: headings, directives, + attestation blocks, fenced code, block quotes, ordered/unordered + lists. Entry points: `parse()` and `parse_file()`. + +- `src/renderer.rs` — serialises a `Document` AST back to canonical + A2ML, making round-trips deterministic. + +- `src/types.rs` — core types: `Document`, `Block`, `Inline`, + `Directive`, `Attestation`, `TrustLevel` (Unverified → Automated → + Reviewed → Verified), `Manifest`. -The crate root is `#![forbid(unsafe_code)]`. Dependencies: `serde`/`serde_derive` -for serialisation, `thiserror` for error types, `criterion` for benchmarks only. +- `src/error.rs` — `A2mlError`: `ParseError`, `Io`, `RenderError`. -== Usage +The crate root is `#![forbid(unsafe_code)]`. Dependencies: +`serde`/`serde_derive` for serialisation, `thiserror` for error types, +`criterion` for benchmarks only. -[source,rust] ----- +# Usage + +```rust use a2ml::{parse, render}; let doc = parse(input_str)?; let output = render(&doc)?; ----- - -== Attestation Trust Levels +``` -[cols="1,3"] -|=== -| Level | Meaning +# Attestation Trust Levels -| `Unverified` | No review — raw agent or tool output -| `Automated` | Processed by a pipeline without human review -| `Reviewed` | Human-reviewed (claimed, not cryptographically proved) -| `Verified` | Formally verified or cryptographically attested -|=== +| Level | Meaning | +|--------------|--------------------------------------------------------| +| `Unverified` | No review — raw agent or tool output | +| `Automated` | Processed by a pipeline without human review | +| `Reviewed` | Human-reviewed (claimed, not cryptographically proved) | +| `Verified` | Formally verified or cryptographically attested | Attestations are syntactic declarations, not cryptographic signatures. Signature verification belongs in the Groove protocol stack. -== Related +# Related + +- [pandoc-a2ml](https://github.com/hyperpolymath/pandoc-a2ml) — Pandoc + reader/writer for A2ML -* link:https://github.com/hyperpolymath/pandoc-a2ml[pandoc-a2ml] — Pandoc reader/writer for A2ML -* link:https://github.com/hyperpolymath/a2ml-haskell[a2ml-haskell] — Haskell implementation +- [a2ml-haskell](https://github.com/hyperpolymath/a2ml-haskell) — + Haskell implementation -== License +# License -MPL-2.0. See link:LICENSE[LICENSE]. +MPL-2.0. See [LICENSE](LICENSE).