The Manifest

The AMES manifest is the structured cataloging layer at the beginning of every .ax.md translation file.

It repeats key signals from the canonical HTML page, such as page identity and permissions, and adds declarations that exist nowhere else: where the substantive content is, what the page is about, and what visual or media context a machine reader may need.

The manifest is written in YAML and enclosed by --- delimiters, but it is a defined AMES structure. It allows a consuming system to determine, before traversing the body:

• what page the document translates;
• who published it;
• what automated uses are permitted;
• where the substantive content is located;
• what the page is principally about;
• what visual context may be relevant; and
• whether any media is essential to understanding the page.

Its block order is normative. Implementations must preserve the defined sequence of field groups, use the specified field names and values, and must not introduce custom fields. Publishers and tool authors should take particular care when using general-purpose YAML serializers, some of which reorder or alphabetize keys by default.

The manifest contains six blocks:

1. Page Identity
2. Permissions
3. Content
4. Topic Signals
5. Visual Register
6. Key Media

Blocks 1 through 3 are required. Blocks 4 through 6 are optional. When optional blocks are included, they must appear in the order shown.

Required Blocks

Every Agent Exchange document must include the first three blocks in the following sequence.

1. Page Identity

The Page Identity block connects the Agent Exchange document to the human-facing page it translates.

It includes:

• ames_version: The AMES version used by the document. For this specification, the value is "0.9".
• canonical_url: The absolute URL of the human-facing source page.
• publisher: The publisher responsible for the page.
• title: The page title, matching the HTML source.
• locale: Optional locale information.
• date_published: Optional publication timestamp in the format required by the specification.
• date_modified: Optional modification timestamp in the format required by the specification.

Identity fields should be derived from the canonical page or the publisher’s authoritative site configuration. A generator should not silently invent or substitute values.

2. Permissions

The Permissions block carries the page-level automated-use declaration.

It must correspond to the ames-policy state declared in the canonical page’s HTML.

When the publisher uses the native AMES permissions framework, the block declares the four actions:

• index
• ephemeral
• store
• train

Each action is assigned 1 to allow the use or 0 to deny it.

When the publisher uses an external policy, rights statement, or licensing framework, the block uses the custom form and, where applicable, supplies the absolute URL of the governing notice.

The manifest must not contradict the permissions declared in the source HTML.

3. Content

The Content block connects the manifest to the translated body.

The content.zone field identifies the zone, or zones, containing the page’s substantive content. A zone is a structural region of the page, marked in the translated body; Translating the Body covers zones in full. This allows a consuming system to locate the primary material without first processing navigation, sidebars, footers, or other supporting regions.

The declared zone names must exactly match the corresponding zone markers in the translated body.

A page may identify a single substantive zone or an array of zones where the source page contains more than one primary content region.

• dynamic_dom: Optional Boolean, defaulting to false. Set to true when client-side scripts alter the structural container sequence of the declared content zone after the initial server response. This is an advisory signal and does not change how structural parity is evaluated.

Worked pages are in the Multiple Content Zones and Dynamic DOM Declaration examples.

Optional Blocks

Publishers may include three additional blocks providing semantic, visual, or media context.

The character limits, permitted values, and maximum array sizes defined by AMES are part of the field requirements. Values exceeding those limits are nonconforming and may be ignored or treated as invalid by a consuming system.

4. Topic Signals

Topic Signals provides concise, high-level categorization of the page.

It may include:

• intended_audience: A single string, limited to 160 characters.
• core_topics: An array of no more than 8 strings, each limited to 40 characters.

These fields should describe the page itself rather than the publisher’s site as a whole.

5. Visual Register

The Visual Register provides limited visual and brand context that may help automated systems interpret, describe, or faithfully represent the page.

It may include:

• logo_url: An absolute URL to the primary logo.
• colors: An array of no more than 3 hexadecimal color values.
• typography: The primary type choices and typographic character, limited to 150 characters.
• visual_direction: A concise description of the page or site aesthetic, limited to 300 characters.

All URLs must be absolute.

The Visual Register is not intended to reproduce a complete design system. It supplies only the principal signals needed to understand the page’s visual identity.

6. Key Media

Key Media identifies media that is essential to a machine reader’s understanding of the page.

The threshold is functional: if omitting the media would materially impair or prevent understanding of the page, it belongs in the Key Media block. Decorative imagery and media that can be omitted without affecting comprehension must not be declared.

Key Media is declared under the top-level media key as a list of items.

Each item contains the following required and optional fields:

• id: Required. A unique identifier within the Agent Exchange document.
• url: Required. An absolute, publicly resolvable URL.
• type: Required. One of diagram, photo, chart, illustration, screenshot, video, audio, or embed.
• alt_text: Required. A human-facing accessibility description.
• transcript_url: Optional. An absolute URL to an existing transcript for video or audio.
• ocr_text: Optional. Text visibly contained within an image.

The id is referenced from the translated body using the ames-media:id form:

![Descriptive alt text](ames-media:exposure-diagram)

A media item declared in the manifest must not also be embedded using its ordinary source URL through standard Markdown image syntax or repeated as a raw URL.

Worked pages are in the Key Media Declaration and Media-Dense Page examples.

Example Manifest

The example below is the manifest of the specification’s worked example, reproduced from the AMES Specification.

---
ames_version: "0.9"
canonical_url: "https://catchlightmag.com/articles/golden-hour-myth/"
publisher: "Catchlight"
title: "The Golden Hour Myth: Why the Best Light Is the Light You Understand"
locale: "en-US"
date_published: "2026-03-18T09:00:00Z"

permissions:
  index: 1
  ephemeral: 1
  store: 0
  train: 0

content:
  zone: "article"

topic_signals:
  intended_audience: "Intermediate to advanced photographers seeking to deepen craft rather than acquire gear."
  core_topics: ["photography", "natural light", "composition", "photographic technique", "visual literacy"]

visual_register:
  logo_url: "https://catchlightmag.com/assets/logo.svg"
  colors: ["#1a1a1a", "#f5f2ee", "#c8773a"]
  typography: "Clean serif headlines with generous leading; neutral sans-serif body."
  visual_direction: "Documentary and fine art photography. High contrast, minimal post-processing."

media:
  - id: "midday-portrait-comparison"
    url: "https://catchlightmag.com/assets/articles/golden-hour-myth/midday-comparison.jpg"
    type: "photo"
    alt_text: "Side-by-side portraits: golden hour at left, managed midday shade at right, producing equally compelling contrast."
---

The zoned Markdown body begins immediately after the closing --- delimiter. A complete manifest in context is in the Semantic Markup example.

Implementation Caution

Do not assume that valid YAML is automatically valid AMES.

A conforming serializer must also preserve:

• the required block sequence;
• the defined field names;
• the required scalar and array forms;
• the permitted values and limits;
• the correspondence between manifest declarations and body markers; and
• the correspondence between manifest permissions and the canonical HTML page.

General-purpose serialization libraries may reorder keys, normalize scalar values, alter quoting, omit required fields, or otherwise produce YAML that is syntactically valid but nonconforming under AMES. Implementations should generate and validate the manifest against the AMES structure rather than relying on generic YAML validity alone.