// SPDX-License-Identifier: CC-BY-SA-4.0
// (PMPL-1.0-or-later preferred; MPL-2.0 required for VS Code Marketplace)
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

= vscode-a2ml
:author: Jonathan D.A. Jewell
:toc: preamble
:icons: font

== Overview

VS Code extension providing syntax highlighting, language configuration, and snippets for
https://github.com/hyperpolymath/standards/tree/main/a2ml[A2ML (Attested Markup Language)]
files.

A2ML is the universal manifest format for AI agents, providing structured metadata,
attestation blocks, lifecycle hooks, and gatekeeper configuration for repositories.

== Installation

=== From the Marketplace

[source]
----
ext install hyperpolymath.a2ml
----

Or search for "A2ML" in the VS Code Extensions panel.

=== From VSIX

[source,sh]
----
code --install-extension vscode-a2ml-0.1.0.vsix
----

== Features

=== Syntax Highlighting

Full TextMate grammar for `.a2ml` files, highlighting:

[cols="1,2"]
|===
| Element | TextMate Scope

| Comments (`#`)
| `comment.line`

| SPDX headers
| `keyword.other.spdx`

| Section delimiters (`---`)
| `markup.heading`

| Key names
| `entity.name.tag`

| Attestation keywords
| `keyword.other.attestation`

| Strings (single and double quoted)
| `string.quoted`

| Dates (ISO 8601)
| `constant.other.date`

| URLs
| `markup.underline.link`

| Booleans
| `constant.language.boolean`
|===

=== Language Configuration

* **Line comments** toggled with `Ctrl+/` (uses `#` prefix)
* **Bracket matching** for `{}`, `[]`, `()`
* **Auto-closing pairs** for brackets, parentheses, and quotes
* **Surrounding pairs** for wrapping selected text
* **Folding** on `---` section delimiters

=== Snippets

Seven snippets for common A2ML patterns:

[cols="1,1,3"]
|===
| Prefix | Name | Description

| `spdx`
| SPDX Header
| SPDX license identifier and copyright header with tab stops for license, year, and author

| `manifest`
| A2ML Manifest
| Complete AI manifest template with canonical locations, critical invariants, and lifecycle hooks

| `attest`
| Attestation Block
| Attestation block with trust level choice (`high`/`medium`/`low`), signature, and timestamp

| `gatekeeper`
| Gatekeeper Section
| Gatekeeper protocol configuration with enforcement level and agent list

| `---`
| Section Delimiter
| Section delimiter with key name

| `kv`
| Key-Value Pair
| Simple key-value pair

| `checkpoint`
| Checkpoint
| Checkpoint entry with id, status choice (`pending`/`complete`/`blocked`), and verification flag
|===

== Configuration

The extension activates automatically for files with the `.a2ml` extension. No additional
configuration is required.

=== File Association

The extension registers the `a2ml` language ID for `.a2ml` files. You can also manually
associate other file patterns in your VS Code settings:

[source,json]
----
{
  "files.associations": {
    "*.a2ml": "a2ml",
    "AI-MANIFEST.*": "a2ml"
  }
}
----

== Extension Details

[cols="1,2"]
|===
| Field | Value

| Publisher
| `hyperpolymath`

| Display Name
| A2ML (Attested Markup Language)

| VS Code Compatibility
| ^1.75.0

| Category
| Programming Languages

| Grammar Scope
| `source.a2ml`
|===

== Directory Layout

[source]
----
editors/vscode/
  package.json                  -- Extension manifest
  language-configuration.json   -- Bracket/comment/folding rules
  syntaxes/
    a2ml.tmLanguage.json        -- TextMate grammar (full highlighting)
    a2ml.json                   -- Additional syntax definitions
  snippets/
    a2ml.json                   -- 7 snippet definitions
  icons/                        -- Extension icons
  src/                          -- Extension source
----

== Licensing

SPDX-License-Identifier: MPL-2.0

PMPL-1.0-or-later is preferred. MPL-2.0 is used as a fallback because the VS Code
Marketplace requires an OSI-approved license. See link:LICENSE[LICENSE] for the MPL-2.0
text and link:LICENSE-PMPL[LICENSE-PMPL] for the PMPL-1.0-or-later text.

== Part of the A2ML Ecosystem

This extension is part of the link:../../README.adoc[A2ML specification and tooling] in the
https://github.com/hyperpolymath/standards[standards monorepo]. See the parent directory
for language bindings, Pandoc support, the validation GitHub Action, and the CLI.
