# AXAG — Agent Experience Accessibility Guidelines

> AXAG (Agent Experience Accessibility Guidelines) is a standard for annotating web UIs so AI agents can discover and invoke what a page does, instead of scraping it. Authors add `axag-*` attributes to existing HTML; tooling turns those into a Semantic Manifest and MCP or WebMCP tools an agent runtime can register.

Source: https://axag.org  ·  Generated from the documentation, in sidebar order.


# Introduction

## What is Agent Experience (AX)?

Source: https://axag.org/docs/intro/what-is-ax

**Agent Experience (AX)** is a design discipline that treats AI agents as first-class product consumers. Just as User Experience (UX) designs for human perception, cognition, and behavior, AX designs for agent perception, planning, and execution.

## The Problem

Modern software interfaces are designed exclusively for human users. Every button label, layout decision, navigation pattern, and interaction flow is optimized for human visual processing and manual interaction. When AI agents attempt to interact with these interfaces, they must:

1. **Infer meaning** from visual layout, CSS classes, and button text
2. **Guess relationships** between form fields, validation rules, and submission actions
3. **Reconstruct intent** from ambiguous labels like "Submit", "Go", or "Process"
4. **Navigate state machines** that were never documented for non-human consumers
5. **Handle side effects** that are only described in human-readable tooltips or documentation

This approach is fundamentally brittle. It fails whenever:

- A CSS class name changes
- A button label is reworded
- A component is replaced with a different visual design
- A page layout is restructured
- Localization changes text content
- Dynamic rendering alters the DOM tree
- Anti-bot defenses are activated

## The AX Discipline

AX addresses this by establishing a parallel design dimension:

| Dimension | UX (Human) | AX (Agent) |
|-----------|-----------|------------|
| **Perception** | Visual rendering, color, layout | Semantic annotations, structured metadata |
| **Understanding** | Labels, tooltips, documentation | Declared intent, entity types, action semantics |
| **Interaction** | Click, type, drag, scroll | Structured operation invocation |
| **Validation** | Visual error messages, inline hints | Declared constraints, preconditions, error codes |
| **Safety** | Confirmation dialogs, undo buttons | Risk classification, approval requirements, idempotency declarations |
| **Discovery** | Navigation menus, search bars | Semantic manifests, tool registries |

AX does not replace UX. AX complements UX by making the semantic layer of an interface explicit and machine-readable.

## Core Principles of AX

### 1. Agents Are Consumers, Not Scrapers

An agent should be able to discover what operations are available, what parameters they require, what constraints apply, and what side effects they produce — without parsing visual layout or inferring meaning from presentation.

### 2. Intent Must Be Explicit

A button labeled "Go" tells a human what to do through visual context. An agent has no visual context. AX requires that every interactive element carries declared intent: `product.search`, `order.cancel`, `ticket.escalate`.

### 3. Constraints Must Be Declared

Validation rules that only exist in client-side JavaScript are invisible to agents. AX requires that constraints — required fields, value ranges, format rules, preconditions — are part of the semantic contract.

### 4. Safety Must Be Engineered

An agent that can submit a form can also submit a destructive operation. AX requires that risk levels, confirmation requirements, approval gates, and side-effect declarations are part of every interaction's metadata.

### 5. Discovery Must Be Structured

Agents cannot browse a navigation menu visually. AX requires that available operations are discoverable through structured manifests and tool registries.

## AX vs Accessibility (A11Y)

AX is conceptually adjacent to accessibility but serves a different consumer:

| Aspect | A11Y | AX |
|--------|------|-----|
| **Consumer** | Humans with disabilities | AI agents |
| **Medium** | Screen readers, keyboard navigation | Semantic manifests, tool registries |
| **Goal** | Equal access for all humans | Machine-readable interaction contracts |
| **Standard** | WCAG, ARIA | AXAG |
| **Annotations** | `aria-label`, `role`, `aria-describedby` | `axag-intent`, `axag-entity`, `axag-action-type` |

Both disciplines share a common insight: **explicit semantics improve interaction quality for non-visual consumers.** ARIA annotations help screen readers understand interface structure. AXAG annotations help agent runtimes understand interaction semantics.

## Why AX Matters Now

The proliferation of AI agents — from customer service bots to autonomous workflow engines — has created an urgent need for reliable, deterministic agent–interface interaction. Current approaches rely on:

- **Screen scraping** — parsing rendered DOM to extract data and trigger actions
- **Prompt engineering** — instructing LLMs to interpret screenshots or HTML dumps
- **Custom API integration** — building bespoke connectors for every product

Each of these approaches is expensive, brittle, and non-portable.

AX, implemented through the AXAG standard, provides a **universal semantic contract layer** that any agent runtime can consume without product-specific integration work.

## Next Steps

- [What is AXAG?](/docs/intro/what-is-axag) — Learn about the annotation standard that implements AX
- [Why Human Interfaces Fail Agents](/docs/intro/why-human-interfaces-fail-agents) — Understand the failure modes in detail
- [Core Concepts](/docs/concepts/agent-experience) — Explore the conceptual foundations

## What is AXAG?

Source: https://axag.org/docs/intro/what-is-axag

**AXAG (Agent Experience Accessibility Guidelines)** is an annotation standard that makes interface semantics explicit and machine-readable for AI agents. It defines a **semantic interaction contract** — a formal declaration of what each interface element means, what it does, what it requires, and what it produces.

> *AX defines the discipline. AXAG defines the executable semantic contract.*

## AXAG Is Not Just Metadata

AXAG is frequently misunderstood as a metadata format — a way to add descriptive labels to UI elements. This undersells its purpose.

AXAG is a **semantic interaction contract**. It declares:

| Dimension | What It Answers |
|-----------|----------------|
| **Intent** | What is this interaction trying to accomplish? |
| **Entity** | What domain object does this interaction operate on? |
| **Action Type** | Is this a read, write, delete, or navigate operation? |
| **Parameters** | What inputs does this interaction require? |
| **Constraints** | What rules govern valid inputs? |
| **Preconditions** | What state must be true before execution? |
| **Postconditions** | What state will be true after execution? |
| **Scope** | What boundary (tenant, user, org) does this operate within? |
| **Risk Level** | How dangerous is this operation? |
| **Confirmation** | Does this require explicit confirmation? |
| **Approval** | Does this require multi-party approval? |
| **Idempotency** | Is it safe to repeat this operation? |
| **Side Effects** | What observable changes does this produce? |

This contract becomes the **source of truth** for two downstream artifacts:

1. **Semantic Manifest** — A structured document that exposes all available operations
2. **MCP Tool Registry** — Generated tool definitions that agent runtimes consume

## The Architecture

```mermaid
graph TD
    A[Human Interface] --> B[AXAG Semantic Contract]
    B --> C[Semantic Manifest]
    C --> D[MCP Tool Registry]
    D --> E[Agent Runtime]

    style A fill:#e0f2fe,stroke:#0284c7
    style B fill:#ddd6fe,stroke:#7c3aed
    style C fill:#fef3c7,stroke:#d97706
    style D fill:#d1fae5,stroke:#059669
    style E fill:#fee2e2,stroke:#dc2626
```

### Layer 1: Human Interface

The visual, interactive surface designed for human users. Buttons, forms, tables, navigation — everything a human sees and interacts with.

### Layer 2: AXAG Semantic Contract

The machine-readable contract that declares the **meaning, intent, constraints, and execution semantics** of interface interactions. This contract exists as annotations on UI elements.

### Layer 3: Semantic Manifest

A derived artifact generated from AXAG annotations. It exposes **discoverable, structured operations** with parameter schemas, constraint declarations, and safety metadata.

### Layer 4: MCP Tool Registry

A generated tool surface following the Model Context Protocol (MCP) specification. Agent runtimes consume this registry to discover and invoke operations **deterministically**.

### Layer 5: Agent Runtime

The planning and execution layer. It reads the tool registry, selects appropriate tools, validates constraints, and performs operations — all without scraping or visual inference.

## A Concrete Example

Consider a search button on an e-commerce product page.

### Without AXAG

```html
<button class="btn btn-primary search-btn" onclick="doSearch()">
  Search
</button>
```

An agent looking at this button knows:
- There is a button
- It says "Search"
- It has a CSS class `search-btn`

The agent does **not** know:
- What entity is being searched
- What parameters the search requires
- What scope the search operates within
- Whether the operation has side effects
- What the expected response structure is

### With AXAG

The following annotation syntax is a Proposed Implementation Pattern. The semantic dimensions are normative; the exact attribute syntax may evolve.

```html
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category", "price_min", "price_max", "sort_by"]'
  axag-scope="public"
  axag-risk-level="none"
  axag-idempotent="true"
>
  Search
</button>
```

Now the agent knows:
- ✅ This is a product search operation
- ✅ It operates on the `product` entity
- ✅ It is a read (non-mutating) operation
- ✅ It requires a `query` parameter
- ✅ It optionally accepts `category`, `price_min`, `price_max`, `sort_by`
- ✅ It operates within the `catalog` scope
- ✅ It has no risk
- ✅ It is idempotent — safe to retry

## What AXAG Is Not

| AXAG Is | AXAG Is Not |
|---------|-------------|
| A semantic contract standard | A UI component library |
| An annotation format for existing interfaces | A replacement for existing interfaces |
| A source of truth for agent interaction | A visual rendering system |
| Compatible with any frontend framework | Tied to React, Vue, or Angular |
| A specification for what interactions mean | A specification for how interactions look |
| Framework-agnostic metadata | An API definition language like OpenAPI |

## Relationship to Existing Standards

| Standard | Purpose | AXAG Relationship |
|----------|---------|-------------------|
| **ARIA / WCAG** | Accessibility for humans with disabilities | Complementary — AXAG serves agents, not screen readers |
| **OpenAPI** | API contract definition | AXAG annotates UI semantics; OpenAPI defines API endpoints |
| **JSON-LD / Schema.org** | Structured data for search engines | AXAG describes interaction semantics, not content metadata |
| **MCP** | Agent tool protocol | AXAG generates MCP-compatible tool definitions |

## Who Should Use AXAG?

- **Frontend engineers** — Annotate UI elements with semantic contracts
- **Platform teams** — Generate manifests and tool registries from annotations
- **Agent runtime builders** — Consume tool registries for deterministic interaction
- **Product architects** — Design agent-ready interface semantics
- **Standards committees** — Govern annotation vocabulary and conformance levels

## Next Steps

- [Why Human Interfaces Fail Agents](/docs/intro/why-human-interfaces-fail-agents) — Failure modes in detail
- [What Problems AXAG Solves](/docs/intro/what-problems-axag-solves) — The specific problems addressed
- [Getting Started](/docs/getting-started/mental-model) — Build your first annotated interaction

## Why Human Interfaces Fail Agents

Source: https://axag.org/docs/intro/why-human-interfaces-fail-agents

Human interfaces are designed for **visual perception and manual interaction**. They encode meaning through spatial layout, typography, color, iconography, and interactive affordances that humans interpret intuitively. AI agents have none of these perceptual capabilities.

When agents attempt to interact with human-designed interfaces, they encounter systematic failure modes that no amount of prompt engineering or scraping sophistication can reliably solve.

## Failure Mode 1: DOM Instability

Modern frontend frameworks (React, Vue, Angular, Svelte) generate DOM structures dynamically. Class names are hashed, element hierarchies change between renders, and component boundaries shift with every build.

```html
<!-- Build 1 -->
<div class="ProductCard_wrapper__x7kf2">
  <button class="ProductCard_addBtn__m9p1q">Add to Cart</button>
</div>

<!-- Build 2 (after CSS modules rehash) -->
<div class="ProductCard_wrapper__a3bc1">
  <button class="ProductCard_addBtn__z8y2r">Add to Cart</button>
</div>
```

An agent relying on the CSS class `ProductCard_addBtn__m9p1q` will fail silently after the next deployment.

## Failure Mode 2: Ambiguous Labels

Human interfaces frequently use short, context-dependent labels that rely on visual context for disambiguation:

- **"Submit"** — Submit what? A form? An application? A payment?
- **"Delete"** — Delete which entity? Is this reversible?
- **"Go"** — Navigate where? Execute what?
- **"Process"** — Process what? With what parameters?
- **"More"** — More of what? Expand details? Load additional items?

Humans disambiguate these labels through visual context — the surrounding form, the page title, the section heading. Agents cannot reliably perform this disambiguation.

## Failure Mode 3: Hidden State Logic

Many interface interactions depend on state that is only visible through visual indicators:

- A button is grayed out (disabled) because a precondition is not met
- A form field turns red because validation failed
- A modal appears because a confirmation step was triggered
- A loading spinner indicates an async operation in progress

None of this state logic is exposed semantically. An agent cannot determine:
- *Why* a button is disabled
- *What* precondition must be satisfied
- *Whether* a confirmation step will be required
- *What* state transitions are occurring

## Failure Mode 4: Multi-Step Modal Complexity

Complex workflows involve multi-step modals, wizard flows, and conditional form paths:

```
Step 1: Select product → Step 2: Configure options → Step 3: Review → Step 4: Confirm
```

Each step may conditionally show or hide fields based on previous selections. The entire flow is orchestrated through client-side state management that is completely opaque to agents.

## Failure Mode 5: Localization and A/B Testing

- Button text changes by locale: "Search" → "Buscar" → "検索"
- A/B tests change button placement, labels, and behavior
- Feature flags alter available interactions per user segment

Agents that depend on text content or element positioning break whenever these variations change.

## Failure Mode 6: Anti-Bot Defenses

Many applications implement:
- CAPTCHA challenges
- Rate limiting
- Browser fingerprinting
- Behavioral analysis
- IP-based blocking

These defenses treat automated interaction as adversarial by default. AXAG provides a legitimate, sanctioned interaction path that distinguishes authorized agent access from unauthorized scraping.

## Failure Mode 7: Asynchronous State Transitions

Modern SPAs use asynchronous data fetching, optimistic updates, and eventual consistency:

```
User clicks "Place Order"
  → UI shows spinner
  → Payment service processes (3-5 seconds)
  → Inventory service reserves (1-2 seconds)
  → Order service creates order
  → UI shows confirmation
```

An agent has no semantic signal for:
- When the operation completes
- Whether it succeeded or failed
- What the resulting state is
- Whether it is safe to proceed

## Failure Mode 8: Undeclared Side Effects

A "Merge Contacts" button in a CRM might:
- Combine two contact records
- Reassign all related opportunities
- Trigger notification emails
- Update analytics dashboards
- Modify billing records

None of these side effects are declared in the button's HTML. An agent that invokes this action has no way to assess its full impact.

## The Fundamental Problem

All of these failure modes share a common root cause:

> **Human interfaces encode meaning through presentation. Agents need meaning encoded through declaration.**

This is the semantic gap that AXAG closes.

## The Cost of the Semantic Gap

| Impact | Description |
|--------|-------------|
| **Brittle automation** | Scraping-based agents break with every UI deployment |
| **Unsafe mutations** | Agents trigger destructive operations without understanding consequences |
| **Maintenance burden** | Every UI change requires scraper updates |
| **Non-portability** | Scrapers are product-specific; no reuse across applications |
| **Trust deficit** | Organizations cannot trust agent interactions without semantic guarantees |
| **Compliance risk** | Uncontrolled agent mutations may violate regulatory requirements |

## How AXAG Addresses Each Failure Mode

| Failure Mode | AXAG Solution |
|-------------|---------------|
| DOM instability | Semantic annotations are stable across renders |
| Ambiguous labels | `axag-intent` declares explicit purpose |
| Hidden state logic | `axag-preconditions` declares required state |
| Multi-step complexity | `axag-workflow-step` declares flow position |
| Localization changes | Intent identifiers are locale-independent |
| Anti-bot defenses | AXAG provides a sanctioned interaction path |
| Async transitions | `axag-postconditions` declares expected outcomes |
| Undeclared side effects | `axag-side-effects` declares observable changes |

## Next Steps

- [What Problems AXAG Solves](/docs/intro/what-problems-axag-solves) — The specific problems AXAG addresses
- [AXAG as a Semantic Contract](/docs/intro/axag-as-semantic-contract) — Understanding the contract model
- [Getting Started](/docs/getting-started/mental-model) — Build your first annotated interaction

## What Problems AXAG Solves

Source: https://axag.org/docs/intro/what-problems-axag-solves

AXAG addresses a specific class of problems that arise when AI agents attempt to interact with systems designed exclusively for human users.

## Problem 1: Semantic Opacity

**Human interfaces express meaning visually. Agents need meaning expressed declaratively.**

AXAG annotations attach machine-readable intent, entity type, action classification, parameters, and constraints to every interactive element.

## Problem 2: Scraping Fragility

**Screen scraping is the current dominant approach for agent–UI interaction. It is inherently brittle.**

AXAG replaces scraping with stable semantic contracts that survive DOM changes, CSS rehashing, layout restructuring, and localization updates.

## Problem 3: Safety Blindness

**Agents cannot distinguish between low-risk reads and high-risk mutations without explicit declarations.**

AXAG classifies every operation by risk level, declares confirmation and approval requirements, and specifies preconditions that must be satisfied before execution.

## Problem 4: Discovery Failure

**Agents cannot browse navigation menus or scan page layouts to discover available operations.**

The AXAG Semantic Manifest exposes all available operations as structured, queryable metadata — eliminating the need for visual discovery.

## Problem 5: Parameter Ambiguity

**Form fields, dropdowns, and input controls do not declare their semantic role to agents.**

AXAG parameter annotations declare field type, validation rules, required status, format constraints, and relationships between fields.

## Problem 6: Cross-Product Inconsistency

**Every product requires a custom scraper or integration. There is no universal interaction contract.**

AXAG is domain-agnostic. The same annotation vocabulary works across e-commerce, CRM, marketing, analytics, travel, support, and any other product category.

## Problem 7: Governance Vacuum

**Organizations have no standard way to govern, validate, version, or audit agent interaction semantics.**

AXAG provides conformance levels, validation rules, CI integration, and a governance model for controlling how interfaces expose operations to agents.

## The Core Thesis

> If an interface exposes operations to AI agents, the semantics of those operations MUST be explicit, validated, and governed — not inferred from visual presentation.

This is the problem space AXAG occupies. It is not a UI framework, not an API specification, and not a metadata format. It is a **semantic interaction contract standard**.

## Next Steps

- [AXAG as a Semantic Contract](/docs/intro/axag-as-semantic-contract)
- [Who Should Use AXAG](/docs/intro/who-should-use-axag)
- [Core Concepts](/docs/concepts/agent-experience)

## AXAG as a Semantic Contract

Source: https://axag.org/docs/intro/axag-as-semantic-contract

AXAG is frequently described as an "annotation standard." While technically accurate, this description understates its purpose. AXAG is a **semantic interaction contract** — a binding declaration of what an interface element does, what it requires, and what it guarantees.

## Contract vs Metadata

| Aspect | Metadata | Contract |
|--------|----------|----------|
| **Purpose** | Describes an element | Governs interaction with an element |
| **Binding** | Informational | Operational |
| **Validation** | Optional | Required |
| **Drift** | Tolerated | Violation |
| **Consumer** | Documentation tools | Agent runtimes |
| **Failure mode** | Stale information | Broken agent behavior |

When AXAG annotations declare that an operation requires `cart_validated` as a precondition, that is not a suggestion — it is a contract. An agent runtime that ignores this precondition is violating the contract. A manifest that omits this precondition has drifted from the source of truth.

## Contract Dimensions

The AXAG semantic contract expresses these dimensions:

### Intent
What the interaction is trying to accomplish. Example: `checkout.begin`, `product.search`, `ticket.escalate`.

### Entity
The domain object being operated on. Example: `order`, `product`, `ticket`, `campaign`.

### Action Type
The classification of the operation: `read`, `write`, `delete`, `navigate`.

### Parameters
The inputs required and optional for the operation, with type information and validation rules.

### Constraints
Rules that govern valid inputs — value ranges, format requirements, mutual exclusions, conditional requirements.

### Preconditions
State that MUST be true before the operation can execute. Example: `cart_validated`, `user_authenticated`, `inventory_available`.

### Postconditions
State that WILL be true after successful execution. Example: `checkout_session_created`, `order_confirmed`.

### Scope
The boundary within which the operation operates: `user`, `tenant`, `organization`, `global`.

### Risk Level
The danger classification: `none`, `low`, `medium`, `high`, `critical`.

### Safety Boundaries
Confirmation requirements, approval gates, rate limits, and cooldown periods.

### Idempotency
Whether the operation is safe to repeat without unintended side effects.

### Side Effects
Observable changes that the operation produces beyond its primary result.

## The Contract Chain

AXAG annotations are the **source of truth** in a contract chain:

```
AXAG Annotations (source of truth)
    → Semantic Manifest (derived artifact)
    → MCP Tool Registry (generated surface)
    → Agent Runtime (consumer)
```

If the annotations change, the manifest MUST be regenerated. If the manifest changes, the tool registry MUST be regenerated. Drift between any layers in this chain is a **conformance violation**.

## Why "Contract" Matters

Calling AXAG a contract rather than metadata has practical consequences:

1. **Validation is mandatory** — Contracts must be validated. Metadata can be stale.
2. **Drift is a defect** — Contract drift is a bug, not technical debt.
3. **Breaking changes require migration** — Contract changes that break consumers require versioning and migration paths.
4. **Governance is required** — Contracts need ownership, review processes, and change control.

## Next Steps

- [Who Should Use AXAG](/docs/intro/who-should-use-axag)
- [Core Concepts: Semantic Contract](/docs/concepts/semantic-contract)
- [Specification Overview](/docs/specification/overview)

## Who Should Use AXAG

Source: https://axag.org/docs/intro/who-should-use-axag

AXAG is designed for multiple audiences across the software development lifecycle.

## Frontend Engineers
Annotate UI components with semantic contracts. You add `axag-*` attributes to buttons, forms, tables, and navigation elements to declare their intent, parameters, and constraints.

## Platform Teams
Build the tooling that generates Semantic Manifests from annotations, produces MCP tool registries, and validates conformance across the product surface.

## Agent Runtime Builders
Consume tool registries generated from AXAG manifests. Your agents discover operations, validate parameters, and execute actions through the semantic contract rather than through scraping.

## Product Architects
Design interaction semantics for your product. Define the vocabulary of intents, entities, and action types that your product exposes to agents.

## API and Integration Teams
Align AXAG semantic contracts with existing API contracts (REST, GraphQL, gRPC). Ensure that UI-facing operations and API-facing operations share consistent semantics.

## Enterprise Standards Committees
Govern the AXAG vocabulary for your organization. Define conformance levels, review processes, and adoption roadmaps.

## Security and Compliance Teams
Review risk classifications, approval requirements, and safety boundaries declared in AXAG annotations. Validate that high-risk operations are appropriately gated.

## Next Steps

- [Getting Started: Mental Model](/docs/getting-started/mental-model)
- [Core Concepts](/docs/concepts/agent-experience)


# Getting Started

## Mental Model: How AXAG Works

Source: https://axag.org/docs/getting-started/mental-model

Before writing your first annotation, understand the mental model that makes AXAG work.

## The Two Audiences

Every interface element serves two audiences simultaneously:

1. **Human users** — who perceive the element visually and interact manually
2. **AI agents** — who need to discover, understand, and invoke the element programmatically

Traditional interfaces serve only the first audience. AXAG adds a semantic layer that serves the second.

## The Five-Layer Architecture

```mermaid
graph TD
    A["🖥️ Human Interface<br/>(Visual, interactive surface)"] --> B
    B["📋 AXAG Semantic Contract<br/>(Annotations on UI elements)"] --> C
    C["📦 Semantic Manifest<br/>(Structured operation catalog)"] --> D
    D["🔧 MCP Tool Registry<br/>(Generated tool definitions)"] --> E
    E["🤖 Agent Runtime<br/>(Plans, validates, executes)"]
```

### Layer 1: Human Interface
The existing UI. No changes required to visual design, layout, or user interaction patterns.

### Layer 2: AXAG Semantic Contract
Annotations added to UI elements. These annotations declare intent, entity, action type, parameters, constraints, preconditions, risk level, and safety requirements.

### Layer 3: Semantic Manifest
A JSON document generated from annotations. It catalogs every operation available on a page, section, or application with full parameter schemas and safety metadata.

### Layer 4: MCP Tool Registry
Tool definitions generated from the manifest following the Model Context Protocol specification. Each operation becomes a callable tool with typed inputs and safety constraints.

### Layer 5: Agent Runtime
The agent reads the tool registry, plans which tools to invoke, validates parameters against constraints, and executes operations.

## The Key Insight

Agents MUST interact with systems through semantic operations declared in the AXAG contract — not through scraping, prompt interpretation, or visual inference.

This means:
- The agent does **not** parse the DOM to find buttons
- The agent does **not** read button text to guess intent
- The agent does **not** inspect CSS classes to identify elements
- The agent **reads** the Semantic Manifest to discover operations
- The agent **reads** tool definitions to understand invocation contracts
- The agent **validates** parameters against declared constraints before execution

## From UI Element to Agent Action

Here is the complete transformation path for a single UI element:

### Step 1: The UI Element (Human-Facing)
```html title="Before — plain HTML button"
<button onclick="handleCheckout()">Proceed to Checkout</button>
```

### Step 2: Add AXAG Annotations
```html title="After — AXAG-annotated checkout button" showLineNumbers
<button
  axag-intent="checkout.begin"
  axag-entity="order"
  axag-action-type="write"
  axag-required-parameters='["cart_id","payment_method_id","shipping_address_id"]'
  <!-- axag-highlight-start -->
  axag-preconditions='["cart_validated","inventory_reserved"]'
  axag-postconditions='["checkout_session_created"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  <!-- axag-highlight-end -->
  axag-scope="user"
  onclick="handleCheckout()"
>
  Proceed to Checkout
</button>
```

### Step 3: Generate Semantic Manifest Entry
```json title="axag-manifest.json — checkout entry" showLineNumbers
{
  "intent": "checkout.begin",
  "entity": "order",
  "action_type": "write",
  "operation_id": "checkout_begin",
  "description": "Start checkout for a validated cart and create a checkout session.",
  "required_parameters": [
    { "name": "cart_id", "type": "string" },
    { "name": "payment_method_id", "type": "string" },
    { "name": "shipping_address_id", "type": "string" }
  ],
  "optional_parameters": [],
  "risk_level": "high",
  "confirmation_required": true,
  "scope": "user",
  "preconditions": ["cart_validated", "inventory_reserved"],
  "postconditions": ["checkout_session_created"]
}
```

### Step 4: Generate MCP Tool Definition
```json title="MCP tool definition — checkout_begin" showLineNumbers
{
  "name": "checkout_begin",
  "description": "Start checkout for a validated cart and create a checkout session.",
  "input_schema": {
    "type": "object",
    "properties": {
      "cart_id": { "type": "string" },
      "payment_method_id": { "type": "string" },
      "shipping_address_id": { "type": "string" }
    },
    "required": ["cart_id", "payment_method_id", "shipping_address_id"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "high",
    "idempotent": false,
    "confirmation_required": true,
    "approval_required": false,
    "source_intent": "checkout.begin",
    "source_entity": "order"
  }
}
```

### Step 5: Agent Invokes the Tool
The agent runtime:
1. Discovers `checkout_begin` in the tool registry
2. Validates that `cart_id`, `payment_method_id`, and `shipping_address_id` are provided
3. Checks that `cart_validated` and `inventory_reserved` preconditions are met
4. Notes that this is a high-risk mutating operation requiring confirmation
5. Requests user confirmation
6. Executes the operation
7. Verifies that `checkout_session_created` postcondition is satisfied

## Next Steps

- [First Annotated Action](/docs/getting-started/first-annotated-action) — Annotate your first UI element
- [First Semantic Manifest](/docs/getting-started/first-semantic-manifest) — Generate a manifest
- [First Generated Tool](/docs/getting-started/first-generated-tool) — Produce an MCP tool definition

## Your First Annotated Action

Source: https://axag.org/docs/getting-started/first-annotated-action

This guide walks you through annotating a single button with AXAG semantics in under five minutes.

## Scenario

You have a product search button on an e-commerce page. Currently, it looks like this:

```html title="Before — unannotated search"
<div class="search-container">
  <input type="text" id="searchInput" placeholder="Search products..." />
  <button class="btn-search" onclick="searchProducts()">
    Search
  </button>
</div>
```

An agent looking at this HTML cannot determine:
- What entity is being searched
- What parameters are required vs optional
- Whether this operation has side effects
- What scope the search operates within

## Step 1: Identify the Semantic Dimensions

Before annotating, answer these questions:

| Question | Answer |
|----------|--------|
| What is the intent? | Search for products |
| What entity does this operate on? | Product |
| What type of action is this? | Read (non-mutating) |
| What parameters are required? | query |
| What parameters are optional? | category, price_min, price_max |
| What scope does this operate in? | Catalog (public) |
| What is the risk level? | None |
| Is it idempotent? | Yes |

## Step 2: Add AXAG Annotations

The attribute syntax shown below is a Proposed Implementation Pattern.

```html title="After — fully annotated product search" showLineNumbers
<div class="search-container">
  <input
    type="text"
    id="searchInput"
    placeholder="Search products..."
    axag-parameter="query"
    axag-parameter-type="string"
    axag-parameter-required="true"
    axag-parameter-description="Free-text search query for product name, description, or SKU"
  />
  <button
    axag-intent="product.search"
    axag-entity="product"
    axag-action-type="read"
    axag-required-parameters='["query"]'
    axag-optional-parameters='["category","price_min","price_max"]'
    axag-scope="public"
    axag-risk-level="none"
    axag-idempotent="true"
    axag-description="Search the product catalog by text query with optional filters"
    class="btn-search"
    onclick="searchProducts()"
  >
    Search
  </button>
</div>
```

### The same annotation as a macro

The identity, safety and parameter-name attributes fit in one [`axag` macro](/docs/specification/macro-syntax); the description stays longhand:

```html title="After — macro shorthand"
<button
  axag="read:product.search!none?idempotent&scope=public&req=query&opt=category,price_min,price_max"
  axag-description="Search the product catalog by text query with optional filters"
  class="btn-search"
  onclick="searchProducts()"
>
  Search
</button>
```

Both forms produce the same Semantic Manifest. `npx axag fmt` converts between them.

## Step 3: Validate Your Annotation

Check your annotation against these rules:

- ✅ `axag-intent` uses `entity.verb` format
- ✅ `axag-entity` identifies the domain object
- ✅ `axag-action-type` is one of: `read`, `write`, `delete`, `navigate`
- ✅ Required parameters are listed
- ✅ Risk level is appropriate for the action type
- ✅ Idempotency is declared for read operations

## Step 4: Verify the Semantic Contract

The annotation now declares a contract:

> "This button performs a **product search** (a **read** operation on the **product** entity) that **requires** a `query` parameter, **optionally** accepts `category`, `price_min`, and `price_max`, operates within the **catalog** scope, has **no risk**, and is **idempotent**."

An agent reading this contract can:
1. Discover the operation without parsing the DOM
2. Construct valid parameters without guessing
3. Assess safety without inspecting visual indicators
4. Retry safely because idempotency is declared

## Common Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| Missing `axag-intent` | Agent cannot determine purpose | Always declare intent |
| Using `axag-action-type="write"` for a search | Misclassifies a read operation | Use `read` for non-mutating operations |
| Omitting `axag-scope` | Agent cannot determine access boundaries | Always declare scope |
| Setting `axag-risk-level="high"` for a search | Over-classifying a safe operation | Match risk to actual impact |

## Next Steps

- [First Semantic Manifest](/docs/getting-started/first-semantic-manifest) — Generate a manifest from your annotation
- [First Generated Tool](/docs/getting-started/first-generated-tool) — Produce an MCP tool definition

## Your First Semantic Manifest

Source: https://axag.org/docs/getting-started/first-semantic-manifest

The Semantic Manifest is a JSON document generated from AXAG annotations. It catalogs every annotated operation with full parameter schemas, constraints, and safety metadata.

## From Annotation to Manifest

Given the annotation from the previous step:

```html title="Annotated search button (from previous step)"
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category","price_min","price_max"]'
  axag-scope="public"
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Search the product catalog by text query with optional filters"
>
  Search
</button>
```

The generated Semantic Manifest entry is:

```json title="axag-manifest.json — generated output" showLineNumbers
{
  "version": "1.1.0",
  "generated_at": "2026-09-14T00:00:00.000Z",
  "source": {
    "paths": ["src"],
    "tool": "axag-cli",
    "tool_version": "1.0.2"
  },
  "conformance": "intermediate",
  "actions": [
    {
      "intent": "product.search",
      "entity": "product",
      "action_type": "read",
      "operation_id": "product_search",
      "description": "Search the product catalog by text query with optional filters",
      "required_parameters": [
        { "name": "query", "type": "string" }
      ],
      "optional_parameters": [
        { "name": "category", "type": "string" },
        { "name": "price_min", "type": "string" },
        { "name": "price_max", "type": "string" }
      ],
      "risk_level": "none",
      "idempotent": true,
      "scope": "public",
      "source_file": "src/pages/search.html",
      "source_line": 1
    }
  ]
}
```

## Manifest Structure

Every Semantic Manifest contains:

| Field | Purpose |
|-------|---------|
| `version` | The AXAG specification version the manifest conforms to |
| `generated_at` | Timestamp of manifest generation |
| `source` | Where the annotations were read from, and the tool that read them |
| `conformance` | `basic`, `intermediate`, or `full` — computed from the declared metadata |
| `actions` | Array of annotated operation definitions, sorted by intent |

Each action contains the full semantic contract: intent, entity, parameters, safety metadata, and the source location it came from.

:::tip Parameter types
Parameters listed by name (`'["query"]'`) are typed as `string`. To declare types and constraints, use the object form: `axag-required-parameters='[{"name":"price_min","type":"number","min":0}]'`.
:::

## Generation Approaches

Manifests can be generated through:

1. **Build-time extraction** — A build plugin scans annotated HTML/JSX and outputs manifest JSON
2. **Runtime extraction** — A client-side script reads `axag-*` attributes from the live DOM
3. **Static analysis** — A linter or analyzer processes source files without rendering

The recommended approach is **build-time extraction** for production deployments.

## Next Steps

- [First Generated Tool](/docs/getting-started/first-generated-tool) — Map the manifest to an MCP tool
- [Manifest Schema](/docs/semantic-manifest/manifest-schema) — Full manifest schema reference

## Your First Generated Tool

Source: https://axag.org/docs/getting-started/first-generated-tool

MCP tool definitions are generated from the Semantic Manifest. Each manifest operation becomes a callable tool that agent runtimes can discover and invoke.

## From Manifest to Tool

Given the manifest entry from the previous step, the generated MCP tool definition is:

```json title="MCP tool — product_search" showLineNumbers
{
  "name": "product_search",
  "description": "Search the product catalog by text query with optional filters",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Free-text search query for product name, description, or SKU"
      },
      "category": { "type": "string", "description": "Filter by product category" },
      "price_min": { "type": "number", "description": "Minimum price filter" },
      "price_max": { "type": "number", "description": "Maximum price filter" }
    },
    "required": ["query"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "product.search",
    "source_entity": "product"
  }
}
```

## Tool Structure

MCP tool definitions contain:

| Field | Purpose |
|-------|---------|
| `name` | Unique identifier derived from the intent (`product.search` → `product_search`) |
| `description` | Human-readable description for agent planning |
| `input_schema` | JSON Schema for tool parameters |
| `metadata` | Action type, risk, idempotency, confirmation, and the source intent |

## How Agents Use This Tool

An agent runtime:

1. **Discovers** `product_search` in the tool registry
2. **Plans** to use it based on user request (e.g., "Find red running shoes under $100")
3. **Constructs** parameters: `{ "query": "red running shoes", "price_max": 100 }`
4. **Validates** that required parameters are present
5. **Checks safety** — read operation, no risk, no confirmation needed
6. **Executes** the tool
7. **Returns** results to the user

## Next Steps

- [First End-to-End Agent Action](/docs/getting-started/first-end-to-end-agent-action)
- [Tool Generation: Mapping Rules](/docs/tool-generation/mapping-rules)

## First End-to-End Agent Action

Source: https://axag.org/docs/getting-started/first-end-to-end-agent-action

This page walks through a complete agent interaction — from user request to executed operation — powered by AXAG semantic contracts.

## Scenario

A user asks their AI agent: *"Find me blue running shoes under $80."*

## Step 1: Agent Discovers Available Tools

The agent queries the MCP Tool Registry and finds:

```json title="Tool registry — product_search" showLineNumbers
{
  "name": "product_search",
  "description": "Search the product catalog by text query with optional filters",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "category": { "type": "string" },
      "price_min": { "type": "number" },
      "price_max": { "type": "number" }
    },
    "required": ["query"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "product.search",
    "source_entity": "product"
  }
}
```

## Step 2: Agent Plans the Invocation

The agent determines:
- Tool: `product_search`
- Parameters: `query = "blue running shoes"`, `price_max = 80`
- Safety: Read-only, no risk, no confirmation needed → proceed directly

## Step 3: Agent Validates Parameters

- ✅ `query` is present and is a string
- ✅ `price_max` is a number
- ✅ No preconditions to check
- ✅ Safety allows direct execution

## Step 4: Agent Executes

The agent invokes `product_search` with:
```json title="Agent invocation — structured parameters"
{
  "query": "blue running shoes",
  "price_max": 80
}
```

## Step 5: Agent Returns Results

The operation returns matching products. The agent presents them to the user with relevant details.

## What Made This Possible

Without AXAG, the agent would need to:
1. Parse the page DOM to find a search input
2. Guess that the input labeled "Search" is for products
3. Figure out how to apply price filters (dropdown? slider? text input?)
4. Submit the form by simulating a button click
5. Wait for dynamic content to load
6. Scrape the results from rendered DOM elements

With AXAG, the agent:
1. Reads structured tool definitions
2. Constructs typed parameters
3. Invokes a semantic operation
4. Receives structured results

**No scraping. No guessing. No brittle selectors.**

## Next Steps

- [Implementation Prerequisites](/docs/getting-started/implementation-prerequisites)
- [Core Concepts](/docs/concepts/agent-experience)
- [Authoring Guide](/docs/authoring-guide/annotating-buttons)

## Implementation Prerequisites

Source: https://axag.org/docs/getting-started/implementation-prerequisites

Before implementing AXAG, ensure the following prerequisites are in place.

## Technical Prerequisites

1. **Frontend framework** — Any modern framework (React, Vue, Angular, Svelte, plain HTML) is supported
2. **Build toolchain** — A build process that can run extraction plugins (Webpack, Vite, Rollup, esbuild, or similar)
3. **JSON processing** — Ability to generate and serve JSON manifest files
4. **CI/CD pipeline** — For running validation and manifest generation on each build

## Organizational Prerequisites

1. **Vocabulary ownership** — Identify who owns the intent and entity vocabulary for your product
2. **Governance model** — Define who reviews and approves changes to annotations
3. **Agent consumer identification** — Know which agent runtimes will consume your semantic contracts
4. **Risk classification policy** — Define how your organization classifies operation risk levels

## Recommended Knowledge

- Familiarity with HTML data attributes
- Understanding of JSON Schema
- Basic knowledge of the Model Context Protocol (MCP)
- Understanding of your product's domain entities and operations

## Next Steps

- [Core Concepts](/docs/concepts/agent-experience)
- [Authoring Guide](/docs/authoring-guide/annotating-buttons)
- [Specification Overview](/docs/specification/overview)


# Core Concepts

## Core Concept: Agent Experience

Source: https://axag.org/docs/concepts/agent-experience

Agent Experience (AX) is the design discipline that ensures AI agents can discover, understand, and execute interface operations reliably. It is the agent-facing counterpart to User Experience (UX).

## Why a Separate Discipline?

Human users and AI agents consume interfaces through fundamentally different modalities:

| Dimension | Human User | AI Agent |
|-----------|-----------|----------|
| **Perception** | Visual (eyes scan layout) | Structural (reads metadata) |
| **Understanding** | Contextual (infers from surroundings) | Declarative (reads explicit contracts) |
| **Interaction** | Physical (click, type, drag) | Programmatic (invoke operations) |
| **Error recovery** | Intuitive (reads error messages) | Structured (parses error codes) |
| **Trust** | Experiential (learns through use) | Contractual (relies on declared guarantees) |

Designing for both modalities requires explicit attention to agent needs — just as accessibility requires explicit attention to the needs of users with disabilities.

## AX Design Principles

### 1. Declarative Over Inferential
Agents should read explicit declarations, not infer meaning from visual presentation.

### 2. Structured Over Unstructured
Operations should be defined with typed parameters, not loose text descriptions.

### 3. Safe By Default
Destructive operations should require explicit opt-in, not implicit trust.

### 4. Discoverable Over Hidden
Available operations should be cataloged in manifests, not hidden in navigation hierarchies.

### 5. Versioned Over Volatile
Semantic contracts should be versioned and governed, not changed without notice.

## Next Steps

- [Semantic Contract](/docs/concepts/semantic-contract)
- [Intent vs Presentation](/docs/concepts/intent-vs-presentation)

## Core Concept: Semantic Contract

Source: https://axag.org/docs/concepts/semantic-contract

A semantic contract is a formal, machine-readable declaration of what an interface interaction means, what it requires, and what it guarantees. AXAG annotations express semantic contracts.

## Contract vs Description

A **description** tells you about something. A **contract** binds you to something.

When AXAG declares `axag-preconditions='["cart_validated"]'`, this is not informational — it is contractual. It means:
- The operation MUST NOT be invoked unless `cart_validated` is true
- The manifest MUST include this precondition
- The tool definition MUST surface this constraint
- The agent runtime MUST validate this before execution

## Contract Components

Every AXAG semantic contract consists of:

1. **Identity** — Intent and entity declarations
2. **Interface** — Parameters, types, and constraints
3. **Preconditions** — Required state before execution
4. **Postconditions** — Guaranteed state after execution
5. **Safety** — Risk level, confirmation, approval requirements
6. **Execution semantics** — Action type, idempotency, side effects

## Contract Lifecycle

```mermaid
graph LR
    A[Author] --> B[Validate]
    B --> C[Generate Manifest]
    C --> D[Generate Tools]
    D --> E[Agent Consumes]
    E --> F[Monitor Drift]
    F --> A
```

Contracts are authored by frontend engineers, validated by CI, transformed into manifests and tools, consumed by agents, and monitored for drift.

## Next Steps

- [Intent vs Presentation](/docs/concepts/intent-vs-presentation)
- [Specification Overview](/docs/specification/overview)

## Core Concept: Intent vs Presentation

Source: https://axag.org/docs/concepts/intent-vs-presentation

**Presentation** describes how an interaction appears to human users. **Intent** describes what the interaction means semantically.

| Aspect | Presentation | Intent |
|--------|-------------|--------|
| Button text | "Submit" | `order.create` |
| Visual state | Grayed-out button | `precondition: cart_validated` |
| Color coding | Red button | `risk_level: high` |
| Position | Below the form | `action_type: write` |

AXAG captures intent. CSS captures presentation. Both are necessary; only intent is machine-readable.

## Why This Distinction Matters

An agent cannot:
- See that a button is red (and infer it's dangerous)
- See that a button is grayed out (and infer a precondition)
- See that a button is at the bottom of a form (and infer it submits the form)

AXAG makes all of this explicit through declarations rather than visual cues.

## Next Steps

- [Affordances](/docs/concepts/affordances)
- [Constraints](/docs/concepts/constraints)

## Core Concept: Affordances

Source: https://axag.org/docs/concepts/affordances

In UX, an affordance is a property of an object that indicates how it can be used — a button affords clicking, a slider affords dragging.

In AX, affordances are **declared capabilities**. An AXAG-annotated element declares what operations it affords to agents through its `axag-intent` and `axag-action-type` attributes.

## Visual vs Semantic Affordances

| Visual Affordance | Semantic Affordance |
|------------------|---------------------|
| A button shape suggests "clickable" | `axag-action-type="write"` declares "invocable operation" |
| A text field suggests "typeable" | `axag-parameter-type="string"` declares "accepts text input" |
| A dropdown suggests "selectable" | `axag-parameter-type="enum"` declares "accepts constrained value" |

## Agent-Facing Affordances

For agents, affordances MUST be:
- **Explicit** — Declared through annotations, not inferred from appearance
- **Typed** — Carrying parameter type information
- **Scoped** — Bounded by declared context
- **Constrained** — Governed by declared validation rules

## Next Steps

- [Constraints](/docs/concepts/constraints)
- [Preconditions and Postconditions](/docs/concepts/preconditions-postconditions)

## Core Concept: Constraints

Source: https://axag.org/docs/concepts/constraints

Constraints are rules that govern valid inputs and valid execution conditions for an operation. In AXAG, constraints are declared as part of the semantic contract — not hidden in client-side validation logic.

## Types of Constraints

### Value Constraints
Rules about individual parameter values:
- Type constraints: `type: "string"`, `type: "number"`
- Format constraints: `format: "email"`, `format: "date"`
- Range constraints: `min: 0`, `max: 100`
- Enum constraints: `enum: ["draft", "published", "archived"]`
- Pattern constraints: `pattern: "^[A-Z]{2}[0-9]{6}$"`

### Relational Constraints
Rules about relationships between parameters:
- Mutual exclusion: `price_min` and `price_max` cannot be equal
- Conditional requirement: `shipping_address_id` is required when `delivery_method` is "ship"
- Dependency: `payment_method_id` requires `billing_address_id`

### Execution Constraints
Rules about when the operation can execute:
- Preconditions: State that must be true before execution
- Rate limits: Maximum invocation frequency
- Cooldown periods: Minimum time between invocations

## Why Declaring Constraints Matters

Validation rules that exist only in client-side JavaScript are invisible to agents. If a form requires an email format but only validates on blur, an agent has no way to know this until submission fails.

AXAG makes constraints part of the contract, enabling agents to construct valid inputs on the first attempt.

## Next Steps

- [Preconditions and Postconditions](/docs/concepts/preconditions-postconditions)
- [Safety Boundaries](/docs/concepts/safety-boundaries)

## Core Concept: Preconditions and Postconditions

Source: https://axag.org/docs/concepts/preconditions-postconditions

**Preconditions** declare what state MUST be true before an operation can execute. **Postconditions** declare what state WILL be true after successful execution.

## Preconditions

Examples:
- `cart_validated` — The cart must be validated before checkout
- `user_authenticated` — The user must be logged in
- `inventory_reserved` — Inventory must be reserved before payment

Preconditions enable agents to:
1. Check whether execution is safe before invoking
2. Identify what steps must be completed first
3. Plan multi-step workflows automatically

## Postconditions

Examples:
- `checkout_session_created` — A checkout session will exist after execution
- `ticket_assigned` — The ticket will be assigned to an agent
- `order_confirmed` — The order will be in confirmed status

Postconditions enable agents to:
1. Verify operation success
2. Chain operations by using postconditions as preconditions for subsequent steps
3. Report expected outcomes to users

## Workflow Chaining

Preconditions and postconditions enable automatic workflow planning:

```
validate_cart → postcondition: cart_validated
reserve_inventory → precondition: cart_validated → postcondition: inventory_reserved
checkout_begin → precondition: cart_validated, inventory_reserved → postcondition: checkout_session_created
```

An agent can automatically determine the correct execution order.

## Next Steps

- [Context and Scope](/docs/concepts/context-and-scope)
- [Safety Boundaries](/docs/concepts/safety-boundaries)

## Core Concept: Context and Scope

Source: https://axag.org/docs/concepts/context-and-scope

**Scope** defines the boundary within which an operation executes. **Context** provides the environmental information needed for execution.

## Scope Levels

| Scope | Description | Example |
|-------|-------------|---------|
| `global` | Accessible to all users | Public product search |
| `catalog` | Scoped to a product catalog | Category-specific search |
| `tenant` | Scoped to an organizational tenant | Multi-tenant SaaS operations |
| `organization` | Scoped to an organization | Team-level settings |
| `user` | Scoped to an individual user | Profile updates |
| `session` | Scoped to an active session | Cart operations |
| `customer` | Scoped to a customer account | Order history |

## Why Scope Matters

An agent operating within a multi-tenant SaaS product must know that `tenant` scope means operations are isolated to the current tenant. Without this declaration, an agent might attempt cross-tenant operations that should be forbidden.

## Context Inheritance

AXAG supports context inheritance — child elements can inherit scope from parent containers:

```html
<div axag-scope="tenant" axag-tenant-boundary="strict">
  <button axag-intent="user.create" axag-entity="user" axag-action-type="write">
    Add User
  </button>
  <!-- This button inherits scope="tenant" and tenant-boundary="strict" -->
</div>
```

## Next Steps

- [Visibility vs Operability](/docs/concepts/visibility-vs-operability)
- [Role Awareness and Tenant Boundaries](/docs/concepts/role-awareness-tenant-boundaries)

## Core Concept: Visibility vs Operability

Source: https://axag.org/docs/concepts/visibility-vs-operability

**Visibility** means an agent can discover an operation exists. **Operability** means an agent can invoke it.

An operation can be:
- Visible and operable — Discoverable and executable
- Visible but not operable — Discoverable but gated (e.g., requires approval)
- Not visible — Hidden from the agent entirely

This distinction prevents agents from assuming that discovery implies permission.

## Declaring Operability

```html
<button
  axag-intent="user.delete"
  axag-entity="user"
  axag-action-type="delete"
  axag-visible="true"
  axag-operable="false"
  axag-operability-reason="Requires admin approval"
  axag-approval-required="true"
  axag-approval-roles='["admin"]'
>
  Delete User
</button>
```

This tells the agent: you can see this operation exists, but you cannot execute it without admin approval.

## Next Steps

- [Determinism and Trust](/docs/concepts/determinism-and-trust)
- [Safety Boundaries](/docs/concepts/safety-boundaries)

## Core Concept: Determinism and Trust

Source: https://axag.org/docs/concepts/determinism-and-trust

Agents require **deterministic** interactions — the same inputs with the same preconditions should produce the same outcomes. Trust in agent interactions is built on predictable behavior governed by explicit contracts.

## Why Determinism Matters

Non-deterministic interactions create:
- Unpredictable side effects
- Inconsistent operation outcomes
- Difficulty in debugging agent behavior
- Erosion of user trust in agent actions

## How AXAG Enables Determinism

1. **Typed parameters** — Agents know exact input requirements
2. **Explicit preconditions** — Agents verify state before execution
3. **Declared postconditions** — Agents verify expected outcomes
4. **Idempotency declarations** — Agents know if retry is safe
5. **Side effect declarations** — Agents assess full impact before execution

## Trust Model

Trust in AXAG is **contractual**: agents trust the semantic contract, and the contract is validated through CI, monitored for drift, and governed through change control.

## Next Steps

- [Safety Boundaries](/docs/concepts/safety-boundaries)
- [Idempotency and Side Effects](/docs/concepts/idempotency-side-effects)

## Core Concept: Safety Boundaries

Source: https://axag.org/docs/concepts/safety-boundaries

Safety boundaries are explicit declarations that control how and when operations can be executed. They prevent agents from performing dangerous actions without appropriate safeguards.

## Safety Dimensions

### Risk Classification

| Level | Description | Example |
|-------|-------------|---------|
| `none` | No risk — read-only, no side effects | Product search |
| `low` | Minor risk — easily reversible | Adding item to cart |
| `medium` | Moderate risk — state changes that require attention | Updating user profile |
| `high` | Significant risk — financial or data impact | Processing payment |
| `critical` | Maximum risk — irreversible, high-impact | Deleting an account |

### Confirmation Requirements

Operations classified as `high` or `critical` risk SHOULD require explicit confirmation before execution.

```html
<button
  axag-intent="account.delete"
  axag-risk-level="critical"
  axag-confirmation-required="true"
  axag-confirmation-message="This will permanently delete the account and all associated data."
>
  Delete Account
</button>
```

### Approval Requirements

Some operations require multi-party approval before execution:

```html
<button
  axag-intent="payment.refund"
  axag-risk-level="high"
  axag-approval-required="true"
  axag-approval-roles='["finance_manager"]'
  axag-approval-count="1"
>
  Issue Refund
</button>
```

### Rate Limits and Cooldowns

```html
<button
  axag-intent="email.send_bulk"
  axag-risk-level="medium"
  axag-rate-limit="100/hour"
  axag-cooldown="60s"
>
  Send Campaign
</button>
```

## Why Safety Boundaries Are Non-Negotiable

An agent without safety boundaries is equivalent to giving every user root access. Without explicit risk declarations, agents cannot distinguish between browsing products and deleting accounts.

## Next Steps

- [Idempotency and Side Effects](/docs/concepts/idempotency-side-effects)
- [Role Awareness and Tenant Boundaries](/docs/concepts/role-awareness-tenant-boundaries)

## Core Concept: Idempotency and Side Effects

Source: https://axag.org/docs/concepts/idempotency-side-effects

**Idempotency** indicates whether an operation can be safely repeated without unintended consequences. **Side effects** are observable changes produced by an operation beyond its primary result.

## Idempotency

| Declaration | Meaning |
|-------------|---------|
| `axag-idempotent="true"` | Safe to retry — repeated invocations produce the same result |
| `axag-idempotent="false"` | Not safe to retry — repeated invocations may cause duplicates or errors |

Examples:
- Product search → idempotent (searching twice returns the same results)
- Order creation → NOT idempotent (creating twice produces two orders)

## Side Effects

Side effects SHOULD be declared when an operation causes observable changes beyond its primary purpose:

```html
<button
  axag-intent="contact.merge"
  axag-side-effects='["opportunities_reassigned","notification_emails_sent","analytics_updated"]'
>
  Merge Contacts
</button>
```

This tells agents that merging contacts will also reassign opportunities, send notification emails, and update analytics — enabling informed decision-making.

## Next Steps

- [Role Awareness and Tenant Boundaries](/docs/concepts/role-awareness-tenant-boundaries)
- [Safety Boundaries](/docs/concepts/safety-boundaries)

## Core Concept: Role Awareness and Tenant Boundaries

Source: https://axag.org/docs/concepts/role-awareness-tenant-boundaries

Operations in multi-tenant, role-based systems require explicit declarations of who can perform them and within what boundary.

## Role Awareness

```html
<button
  axag-intent="user.delete"
  axag-required-roles='["admin","super_admin"]'
  axag-role-escalation="false"
>
  Delete User
</button>
```

This declares that only `admin` and `super_admin` roles can invoke this operation, and role escalation is not permitted.

## Tenant Boundaries

```html
<div axag-scope="tenant" axag-tenant-boundary="strict">
  <button
    axag-intent="settings.update"
    axag-entity="tenant_settings"
    axag-action-type="write"
  >
    Update Settings
  </button>
</div>
```

The inherited `axag-tenant-boundary="strict"` declaration prevents agents from attempting cross-tenant operations.

## Why These Matter

Without role and tenant declarations:
- An agent might attempt admin operations with user-level credentials
- A multi-tenant agent might inadvertently operate across tenant boundaries
- Privilege escalation paths become invisible

## Next Steps

- [Specification Overview](/docs/specification/overview)
- [Context and Scope](/docs/concepts/context-and-scope)


# AXAG Specification

## AXAG Specification Overview

Source: https://axag.org/docs/specification/overview

**Status:** v1.0.0  
**Classification:** Normative  
**Last Updated:** 2026-03-21

This document provides the normative specification for the Agent Experience Accessibility Guidelines (AXAG) standard. It defines the vocabulary, annotation primitives, required and optional fields, conformance levels, and validation rules that govern AXAG implementations.

## Specification Scope

The AXAG specification defines:

1. **Canonical Vocabulary** — The set of reserved annotation attribute names and their semantics
2. **Annotation Primitives** — The atomic annotation units from which semantic contracts are composed
3. **Field Requirements** — Which fields are required at each conformance level
4. **Semantic Dimensions** — The categories of meaning that annotations can express
5. **Conformance Levels** — The tiers of implementation completeness
6. **Validation Rules** — The rules for checking annotation correctness
7. **Versioning Model** — How the specification evolves

## Content Classification

This specification uses RFC 2119 keywords:

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Content in this specification is classified as:

| Classification | Meaning |
|---------------|---------|
| **Normative** | Binding requirements. Implementations MUST comply. |
| **Recommended** | Best practices. Implementations SHOULD follow. |
| **Informative** | Explanatory context. Not binding. |
| **Example** | Illustrative code or configuration. |
| **Proposed Pattern** | Inferred implementation approach. Not yet canonical. |

## Conformance Levels

AXAG defines three conformance levels:

###  Basic Conformance

Minimum viable annotation. Every annotated element MUST include:

###  Intermediate Conformance

Production-ready annotation. In addition to Basic fields, every annotated element SHOULD include:

###  Full Conformance

Enterprise-grade annotation. In addition to Intermediate fields, annotations SHOULD include all applicable semantic dimensions:

## Annotation Format

AXAG annotations MUST be expressed as HTML data attributes prefixed with `axag-`. The prefix is reserved and MUST NOT be used for non-AXAG purposes.

### Attribute Naming Convention

- All attributes use kebab-case: `axag-intent`, `axag-action-type`
- Array values are JSON-encoded strings: `axag-required-parameters='["a","b"]'`
- Boolean values use string `"true"` or `"false"`
- Enum values use lowercase strings from the defined vocabulary

### Example: Minimal Annotation (Basic Conformance)

```html
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
>
  Search
</button>
```

### Example: Full Annotation (Full Conformance)

```html
<button
  axag-intent="checkout.begin"
  axag-entity="order"
  axag-action-type="write"
  axag-required-parameters='["cart_id","payment_method_id","shipping_address_id"]'
  axag-optional-parameters='["promo_code"]'
  axag-preconditions='["cart_validated","inventory_reserved"]'
  axag-postconditions='["checkout_session_created"]'
  axag-scope="user"
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-side-effects='["inventory_locked","payment_hold_created"]'
  axag-description="Start checkout for a validated cart and create a checkout session"
>
  Checkout
</button>
```

## Specification Sections

The full specification is organized into the following sections:

| Section | Content |
|---------|---------|
| [Canonical Vocabulary](/docs/specification/vocabulary) | Reserved attribute names and allowed values |
| [Annotation Primitives](/docs/specification/annotation-primitives) | Atomic annotation units |
| [Required Fields](/docs/specification/required-fields) | Mandatory fields per conformance level |
| [Optional Fields](/docs/specification/optional-fields) | Additional semantic dimensions |
| [Entities](/docs/specification/entities) | Entity naming conventions |
| [Actions](/docs/specification/actions) | Action type definitions |
| [Parameters](/docs/specification/parameters) | Parameter declaration model |
| [Constraints](/docs/specification/constraints) | Constraint declaration model |
| [Risk Classification](/docs/specification/risk-classification) | Risk level definitions |
| [Safety Boundaries](/docs/specification/safety-boundaries) | Confirmation, approval, rate limits |
| [Confirmation Requirements](/docs/specification/confirmation-requirements) | When and how confirmation is required |
| [Approval Requirements](/docs/specification/approval-requirements) | Multi-party approval model |
| [Context Inheritance](/docs/specification/context-inheritance) | How child elements inherit parent context |
| [Namespacing](/docs/specification/namespacing) | Namespace rules for custom extensions |
| [Versioning](/docs/specification/versioning) | Specification version model |
| [Error Semantics](/docs/specification/error-semantics) | Error code and message conventions |
| [Conformance Levels](/docs/specification/conformance-levels) | Detailed conformance requirements |

## Next Steps

- [Canonical Vocabulary](/docs/specification/vocabulary)
- [Annotation Primitives](/docs/specification/annotation-primitives)
- [Semantic Manifest](/docs/semantic-manifest/what-it-is)

## Canonical Vocabulary

Source: https://axag.org/docs/specification/vocabulary

The AXAG canonical vocabulary defines all reserved attribute names, their types, allowed values, and semantic meaning.

## Reserved Attribute Prefix

The prefix `axag-` is reserved for AXAG annotations. Implementations MUST NOT use this prefix for non-AXAG purposes.

## Identity Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `axag-intent` | `string` | Semantic intent in `entity.verb` format |
| `axag-entity` | `string` | Domain entity being operated on |
| `axag-action-type` | `enum` | Operation classification |
| `axag-description` | `string` | Human-readable description |
| `axag-operation-id` | `string` | Unique operation identifier |

## Parameter Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `axag-required-parameters` | `string[]` | JSON array of required parameter names |
| `axag-optional-parameters` | `string[]` | JSON array of optional parameter names |
| `axag-params-from` | `string` | `#id` of the form whose controls supply parameters |
| `axag-schema` | `string` | Schema binding: `zod:<file>#<export>` or `openapi:[<file>#]<operationId>` |
| `axag-parameter` | `string` | Parameter name (on input elements) |
| `axag-parameter-type` | `string` | Parameter data type |
| `axag-parameter-required` | `boolean` | Whether the parameter is required |
| `axag-parameter-description` | `string` | Parameter description |
| `axag-parameter-format` | `string` | Expected format (email, date, url, etc.) |
| `axag-parameter-enum` | `string[]` | Allowed values for enum parameters |
| `axag-parameter-min` | `number` | Minimum value |
| `axag-parameter-max` | `number` | Maximum value |
| `axag-parameter-pattern` | `string` | Regex pattern for validation |
| `axag-parameter-min-length` | `number` | Minimum string length |
| `axag-parameter-max-length` | `number` | Maximum string length |

## State Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `axag-preconditions` | `string[]` | Required state before execution |
| `axag-postconditions` | `string[]` | Guaranteed state after execution |
| `axag-side-effects` | `string[]` | Observable changes beyond primary result |

## Safety Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `axag-risk-level` | `enum` | `none`, `low`, `medium`, `high`, `critical` |
| `axag-confirmation-required` | `boolean` | Whether explicit confirmation is needed |
| `axag-confirmation-message` | `string` | Message to display for confirmation |
| `axag-approval-required` | `boolean` | Whether multi-party approval is needed |
| `axag-approval-roles` | `string[]` | Roles that can approve |
| `axag-approval-count` | `number` | Number of approvals required |
| `axag-idempotent` | `boolean` | Whether safe to repeat |
| `axag-rate-limit` | `string` | Maximum invocation frequency |
| `axag-cooldown` | `string` | Minimum time between invocations |

## Scope Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `axag-scope` | `enum` | `public`, `user`, `tenant`, `global` |
| `axag-tenant-boundary` | `enum` | `strict` (never crosses tenants) or `relaxed` (cross-tenant access where authorized) |
| `axag-required-roles` | `string[]` | Roles permitted to invoke |
| `axag-role-escalation` | `boolean` | Whether role escalation is permitted |

## Visibility Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `axag-visible` | `boolean` | Whether discoverable by agents |
| `axag-operable` | `boolean` | Whether invocable by agents |
| `axag-operability-reason` | `string` | Why the operation is not operable |

## Workflow Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `axag-workflow-id` | `string` | Workflow identifier |
| `axag-workflow-step` | `number` | Step position in workflow |
| `axag-workflow-total-steps` | `number` | Total steps in workflow |
| `axag-workflow-next` | `string` | Intent of next step |
| `axag-workflow-previous` | `string` | Intent of previous step |

## Versioning Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `axag-version` | `string` | AXAG specification version |
| `axag-deprecated` | `boolean` | Whether this annotation is deprecated |
| `axag-deprecated-replacement` | `string` | Replacement intent for deprecated operations |
| `axag-since` | `string` | Version when this annotation was introduced |

## Action Type Values

| Value | Description |
|-------|-------------|
| `read` | Non-mutating data retrieval |
| `write` | Creates or modifies an entity |
| `delete` | Removes, cancels, or deactivates an entity |
| `navigate` | Changes the view or context without data mutation |

:::note Changed in 1.1
Earlier drafts of this page listed `create` and `mutate`. The manifest schema and all AXAG tooling only ever accepted `write`; use `write` for both.
:::

## Scope Values

| Value | Description |
|-------|-------------|
| `public` | Available without authentication (catalog browsing, help pages) |
| `user` | Affects only the signed-in user's own data |
| `tenant` | Affects data shared across the user's organization |
| `global` | Affects every tenant or the whole platform |

## Risk Level Values

| Value | Description | Typical Actions |
|-------|-------------|-----------------|
| `none` | No risk | Search, browse, read |
| `low` | Easily reversible | Add to cart, bookmark |
| `medium` | Requires attention | Update profile, change settings |
| `high` | Financial or data impact | Process payment, submit application |
| `critical` | Irreversible, high impact | Delete account, purge data |

## Next Steps

- [Annotation Primitives](/docs/specification/annotation-primitives)
- [Required Fields](/docs/specification/required-fields)

## Annotation Primitives

Source: https://axag.org/docs/specification/annotation-primitives

Annotation primitives are the atomic units from which AXAG semantic contracts are composed. Every annotation consists of one or more primitives attached to an HTML element.

## Primitive Categories

### 1. Identity Primitives
Declare what the operation is:
- `axag-intent` — The semantic purpose
- `axag-entity` — The domain object
- `axag-action-type` — The operation classification

### 2. Interface Primitives
Declare what the operation requires:
- `axag-required-parameters` — Mandatory inputs
- `axag-optional-parameters` — Optional inputs
- Parameter detail attributes on input elements

### 3. State Primitives
Declare preconditions and postconditions:
- `axag-preconditions` — Required state before execution
- `axag-postconditions` — Guaranteed state after execution
- `axag-side-effects` — Observable changes

### 4. Safety Primitives
Declare risk and authorization:
- `axag-risk-level` — Danger classification
- `axag-confirmation-required` — Confirmation gate
- `axag-approval-required` — Approval gate
- `axag-idempotent` — Retry safety

### 5. Context Primitives
Declare operational boundaries:
- `axag-scope` — Boundary level
- `axag-required-roles` — Role constraints
- `axag-tenant-boundary` — Tenant isolation (`strict` or `relaxed`)

## Composition Rules

Primitives compose according to these rules:

1. **Identity is mandatory** — Every annotated element MUST have at least `axag-intent`, `axag-entity`, and `axag-action-type`
2. **Safety follows action type** — Mutating actions SHOULD declare risk level
3. **Context is inheritable** — Child elements inherit parent context primitives
4. **Parameters are element-scoped** — Parameter detail attributes attach to input elements

## Next Steps

- [Required Fields](/docs/specification/required-fields)
- [Optional Fields](/docs/specification/optional-fields)

## Macro Syntax

Source: https://axag.org/docs/specification/macro-syntax

The `axag` attribute packs the most common annotation fields into one string. It expands to exactly the longhand `axag-*` attributes an author could have written, so validators, manifests and generated tools are identical whichever form a page uses.

The macro is a Proposed Implementation Pattern in AXAG 1.1. Tooling (`@web-axag/axag-lint`, `axag-cli`, the VS Code extension) supports it; it becomes normative once the 1.1 review period closes.

```html title="Longhand"
<button
  axag-intent="user.deactivate"
  axag-entity="user"
  axag-action-type="write"
  axag-risk-level="critical"
  axag-approval-required="true"
  axag-approval-roles='["security_admin"]'
>Deactivate</button>
```

```html title="Macro"
<button axag="write:user.deactivate!critical?approval&roles=security_admin">Deactivate</button>
```

## Grammar

```text
macro        = action-type ":" intent [ "!" risk-level ] [ "?" pair *( "&" pair ) ]
action-type  = "read" | "write" | "delete" | "navigate"
intent       = entity "." verb                ; lowercase letters and _, as axag-intent
risk-level   = "none" | "low" | "medium" | "high" | "critical"
pair         = key [ "=" value ]              ; a bare key means true
value        = token *( "," token )
token        = 1*( ALPHA / DIGIT / "_" / "-" )
```

No escaping is needed: intents cannot contain `: ! ? & = ,`, so values never collide with separators. Whitespace is not allowed inside the macro.

## Keys

| Key | Expands to | Value |
|-----|-----------|-------|
| `approval` | `axag-approval-required` | `true` / `false` (bare key = `true`) |
| `confirm` | `axag-confirmation-required` | `true` / `false` |
| `idempotent` | `axag-idempotent` | `true` / `false` |
| `async` | `axag-async` | `true` / `false` |
| `scope` | `axag-scope` | `public`, `user`, `tenant`, `global` |
| `tenant` | `axag-tenant-boundary` | `strict`, `relaxed` |
| `roles` | `axag-approval-roles` | comma-separated list |
| `effects` | `axag-side-effects` | comma-separated list |
| `req` | `axag-required-parameters` | comma-separated parameter names |
| `opt` | `axag-optional-parameters` | comma-separated parameter names |

Each key MAY appear at most once. List values become JSON string arrays: `roles=owner,security_admin` is `axag-approval-roles='["owner","security_admin"]'`.

## Rules

1. The macro expands to longhand attributes before any validation, manifest generation or tool generation.
2. `axag-entity` defaults to the part of the intent before the dot. An explicit `axag-entity` overrides it and is not a conflict.
3. Longhand attributes MAY sit next to the macro to add fields the grammar cannot express: `axag-description`, `axag-preconditions`, `axag-postconditions`, typed parameter objects, and list items containing spaces.
4. A longhand attribute that sets the same field as the macro to a different value is an error (**AXAG-LINT-028**). Implementations use the longhand value and report the conflict.
5. A macro that does not match the grammar is an error (**AXAG-LINT-027**), reported with the column where parsing failed. Parts that do parse still apply.
6. An empty `axag` attribute is ignored. In JSX, `axag={spec}` is a dynamic value and is not read as a macro.

## Examples

| Macro | Meaning |
|-------|---------|
| `read:product.search!none?idempotent&req=query&opt=category,price_max` | Idempotent search with one required and two optional parameters |
| `write:cart.add_item!low?idempotent=false&effects=cart_updated` | Non-idempotent write with a side effect |
| `delete:invoice.void!high?confirm&idempotent&scope=tenant&tenant=strict` | Confirmed, tenant-bound delete |
| `navigate:settings.open?scope=user` | Navigation, no risk level declared |

## Converting existing pages

`axag-cli` rewrites files in either direction without touching other attributes:

```bash
npx axag fmt src --to macro      # longhand → macro
npx axag fmt src --to longhand   # macro → longhand
npx axag fmt src --check         # CI: fail if any file isn't in macro form
```

## Next Steps

- [Annotation Attributes Reference](/docs/reference/annotation-attributes)
- [Required Fields](/docs/specification/required-fields)

## Required Fields

Source: https://axag.org/docs/specification/required-fields

At minimum (Basic Conformance), every AXAG-annotated element MUST include:

1. **`axag-intent`** — The semantic intent in `entity.verb` format (e.g., `product.search`, `order.create`)
2. **`axag-entity`** — The domain entity being operated on (e.g., `product`, `order`, `ticket`)
3. **`axag-action-type`** — The operation classification (`read`, `write`, `delete`, `navigate`)

At Intermediate Conformance, these additional fields are REQUIRED:

4. **`axag-required-parameters`** — JSON array of required parameter names
5. **`axag-scope`** — The operational boundary
6. **`axag-risk-level`** — The risk classification
7. **`axag-description`** — Human-readable operation description

Implementations that claim conformance at a given level MUST include all fields required at that level and all lower levels.

## Optional Fields

Source: https://axag.org/docs/specification/optional-fields

Optional fields extend the semantic contract with additional dimensions. They are RECOMMENDED for Full Conformance and MAY be included at any level.

## Parameter Fields
- `axag-optional-parameters` — Parameters that are accepted but not required
- `axag-parameter-*` attributes on input elements for detailed parameter metadata

## State Fields
- `axag-preconditions` — Required state before execution
- `axag-postconditions` — Guaranteed state after execution
- `axag-side-effects` — Observable changes

## Safety Fields
- `axag-confirmation-required`, `axag-confirmation-message`
- `axag-approval-required`, `axag-approval-roles`, `axag-approval-count`
- `axag-idempotent`
- `axag-rate-limit`, `axag-cooldown`

## Access Control Fields
- `axag-required-roles`
- `axag-role-escalation`
- `axag-tenant-boundary`

## Workflow Fields
- `axag-workflow-id`, `axag-workflow-step`, `axag-workflow-total-steps`

## Visibility Fields
- `axag-visible`, `axag-operable`, `axag-operability-reason`

## Entities

Source: https://axag.org/docs/specification/entities

An entity is the domain object that an AXAG-annotated operation acts upon. Entities are declared via the `axag-entity` attribute.

## Naming Conventions

- Entity names MUST be lowercase, singular nouns: `product`, `order`, `ticket`, `campaign`
- Compound entities use underscore separation: `shopping_cart`, `user_profile`, `tenant_settings`
- Entity names SHOULD match the domain model used by the application's backend

## Common Entities by Domain

| Domain | Entities |
|--------|----------|
| E-Commerce | `product`, `cart`, `order`, `payment`, `shipment`, `return` |
| CRM | `lead`, `contact`, `opportunity`, `account`, `pipeline` |
| Marketing | `campaign`, `audience`, `experiment`, `template` |
| Support | `ticket`, `agent`, `knowledge_article`, `escalation` |
| Travel | `flight`, `hotel`, `booking`, `itinerary`, `reservation` |
| Analytics | `report`, `dashboard`, `dataset`, `metric`, `alert` |
| Jobs | `job`, `application`, `candidate`, `interview` |

## Entity Relationships

When operations span multiple entities, use the primary entity in `axag-entity` and declare related entities in parameters or side effects.

## Actions

Source: https://axag.org/docs/specification/actions

The `axag-action-type` attribute classifies the nature of an operation.

## Action Types

| Type | Semantic | Side Effects | Idempotent by Default |
|------|----------|-------------|----------------------|
| `read` | Retrieves data without modification | None | Yes |
| `write` | Creates or modifies an entity | Entity creation or state change | Depends — declare `axag-idempotent` |
| `delete` | Removes an entity | Entity removal | Depends |
| `navigate` | Changes view context without data mutation | None | Yes |

## Rules

- `read` and `navigate` actions SHOULD have `axag-risk-level="none"` unless special circumstances apply
- `write` and `delete` actions MUST declare `axag-risk-level`
- `delete` actions SHOULD have `axag-confirmation-required="true"` unless the deletion is trivially reversible
- `write` actions that produce financial impact SHOULD be classified as `high` or `critical` risk

## Parameters

Source: https://axag.org/docs/specification/parameters

Parameters are the inputs required and accepted by an AXAG-annotated operation.

## Declaration Methods

### On the action element:
```html
<button
  axag-intent="product.search"
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category","price_min","price_max"]'
>Search</button>
```

### On individual input elements:
```html
<input
  axag-parameter="query"
  axag-parameter-type="string"
  axag-parameter-required="true"
  axag-parameter-description="Search query text"
  axag-parameter-min-length="1"
  axag-parameter-max-length="200"
/>
```

## Parameter Types
`string`, `number`, `boolean`, `date`, `datetime`, `enum`, `array`, `object`

## Parameter Constraints
- `axag-parameter-min` / `axag-parameter-max` — Numeric range
- `axag-parameter-min-length` / `axag-parameter-max-length` — String length
- `axag-parameter-pattern` — Regex validation
- `axag-parameter-enum` — Allowed values
- `axag-parameter-format` — Format hint (email, url, phone, date, etc.)

## Constraints

Source: https://axag.org/docs/specification/constraints

Constraints govern valid inputs and execution conditions. They MUST be declared in annotations, not hidden in client-side validation logic.

## Value Constraints
Applied to individual parameters: type, format, range, pattern, enum, length.

## Relational Constraints
Relationships between parameters: mutual exclusion, conditional requirements, dependencies.

## Execution Constraints
State requirements: preconditions, rate limits, cooldown periods, temporal windows.

## Declaration Example
```html
<button
  axag-intent="booking.create"
  axag-entity="reservation"
  axag-action-type="write"
  axag-required-parameters='["check_in","check_out","guests"]'
  axag-constraints='{"check_out_after_check_in": "check_out > check_in", "max_guests": "guests <= 10"}'
  axag-preconditions='["room_available"]'
>
  Book Room
</button>
```

## Risk Classification

Source: https://axag.org/docs/specification/risk-classification

Every mutating operation MUST declare a risk level. Risk classification drives safety requirements.

| Level | Description | Required Safety |
|-------|-------------|----------------|
| `none` | No risk (reads, navigation) | None |
| `low` | Easily reversible (cart operations) | None required, logging recommended |
| `medium` | State changes requiring attention | Confirmation recommended |
| `high` | Financial or significant data impact | Confirmation MUST be required |
| `critical` | Irreversible, high-impact operations | Confirmation AND approval MUST be required |

## Classification Guidelines

- **Payment processing** → `high`
- **Account deletion** → `critical`
- **Profile update** → `medium`
- **Adding bookmark** → `low`
- **Searching products** → `none`

Implementations MUST NOT classify a `delete` action as `none` risk unless the deletion is trivially reversible (e.g., removing an unsaved draft).

## Safety Boundaries

Source: https://axag.org/docs/specification/safety-boundaries

Safety boundaries are declared in the annotation and enforced in two places: the agent runtime in the page, and the server that receives the call. A declaration alone constrains nothing — an agent holding the page's credentials can call the API directly — so an implementation MUST enforce `confirmation_required`, `approval_required`, `required_roles` and `tenant_boundary` on the server for any action at `high` risk or above. The page's enforcement is what gives a person the chance to refuse; see [Safety Enforcers](/docs/frameworks/safety).

Safety boundaries define the guardrails around operation execution. This section defines the normative requirements for safety declarations.

## Confirmation Requirements
Operations with `risk_level` of `high` or `critical` MUST declare `axag-confirmation-required="true"`.

## Approval Requirements
Operations that require multi-party authorization MUST declare `axag-approval-required="true"` with `axag-approval-roles` and `axag-approval-count`.

## Rate Limits
Operations subject to rate limiting SHOULD declare `axag-rate-limit` using the format `{count}/{period}` (e.g., `100/hour`, `10/minute`).

## Cooldown Periods
Operations that require a minimum interval between invocations SHOULD declare `axag-cooldown` using duration format (e.g., `60s`, `5m`, `1h`).

## Safety Matrix

| Action Type | Minimum Risk | Confirmation | Approval |
|------------|-------------|-------------|---------|
| `read` | `none` | No | No |
| `navigate` | `none` | No | No |
| `write` | `low` | Required for `high`+ | For regulated or high-impact changes |
| `delete` | `medium` | Required | Recommended |

## Confirmation Requirements

Source: https://axag.org/docs/specification/confirmation-requirements

Confirmation requirements gate operation execution behind explicit user or agent acknowledgment.

## When Confirmation Is Required
- `risk_level` is `high` or `critical`
- The operation produces irreversible side effects
- Financial transactions exceed defined thresholds

## Declaration
```html
<button
  axag-intent="order.cancel"
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-confirmation-message="This will cancel order #{{order_id}} and initiate a refund. This cannot be undone."
>Cancel Order</button>
```

## Agent Runtime Behavior
When `axag-confirmation-required="true"`, agent runtimes MUST:
1. Present the confirmation message to the user
2. Wait for explicit confirmation
3. Only proceed upon affirmative response
4. Log the confirmation event

## Approval Requirements

Source: https://axag.org/docs/specification/approval-requirements

Approval requirements gate operations behind multi-party authorization. These are distinct from confirmations — approvals require a different person or role to authorize.

## Declaration
```html
<button
  axag-intent="refund.process"
  axag-risk-level="high"
  axag-approval-required="true"
  axag-approval-roles='["finance_manager","finance_director"]'
  axag-approval-count="1"
>Process Refund</button>
```

## Approval Model
- `axag-approval-roles` — Roles authorized to approve
- `axag-approval-count` — Number of approvals required (default: 1)
- The invoking agent/user cannot self-approve

## Agent Runtime Behavior
When `axag-approval-required="true"`, agent runtimes MUST:
1. Submit an approval request rather than executing directly
2. Notify the appropriate approval roles
3. Wait for the required number of approvals
4. Execute only after all approvals are received

## Context Inheritance

Source: https://axag.org/docs/specification/context-inheritance

AXAG supports context inheritance — child elements inherit scope, tenant, and role context from parent containers.

## Inheritance Rules
1. `axag-scope` on a parent element applies to all child annotations
2. `axag-tenant-boundary` on a parent element applies to all children
3. `axag-required-roles` on a parent element constrains all children
4. Child elements MAY override inherited context with more restrictive values
5. Child elements MUST NOT override inherited context with less restrictive values

## Example
```html
<section axag-scope="tenant" axag-tenant-boundary="strict" axag-required-roles='["admin"]'>
  <!-- Both buttons inherit scope="tenant", tenant-boundary="strict", required-roles=["admin"] -->
  <button axag-intent="user.create" axag-entity="user" axag-action-type="write">Add User</button>
  <button axag-intent="user.delete" axag-entity="user" axag-action-type="delete"
    axag-required-roles='["super_admin"]'>Delete User</button>
  <!-- Delete overrides to require super_admin (more restrictive) — valid -->
</section>
```

## Namespacing

Source: https://axag.org/docs/specification/namespacing

Organizations MAY extend the AXAG vocabulary with custom attributes using namespaced prefixes.

## Rules
- Custom attributes MUST use the format `axag-x-{namespace}-{attribute}`
- The `x-` prefix indicates an extension attribute
- Extensions MUST NOT conflict with reserved AXAG attribute names
- Extensions SHOULD be documented in the organization's AXAG governance policy

## Example
```html
<button
  axag-intent="order.create"
  axag-entity="order"
  axag-action-type="write"
  axag-x-acme-billing-code="SALES-001"
  axag-x-acme-department="sales"
>Create Order</button>
```

## Specification Versioning

Source: https://axag.org/docs/specification/versioning

The AXAG specification follows semantic versioning: `MAJOR.MINOR.PATCH`.

## Version Rules
- **MAJOR** — Breaking changes to normative requirements
- **MINOR** — New optional fields or conformance requirements
- **PATCH** — Clarifications, typo fixes, informative content updates

## Annotation Versioning
Annotations MAY declare the specification version they conform to:
```html
<button axag-version="1.0.0" axag-intent="product.search" ...>Search</button>
```

## Backward Compatibility
- MINOR versions MUST be backward-compatible with the same MAJOR version
- Deprecated attributes MUST remain valid for at least one MINOR version after deprecation
- Deprecation MUST be declared via `axag-deprecated="true"` and `axag-deprecated-replacement`

## Error Semantics

Source: https://axag.org/docs/specification/error-semantics

AXAG defines error codes and semantics for annotation validation and runtime execution failures.

## Validation Error Codes

| Code | Name | Description |
|------|------|-------------|
| `AXAG-001` | Missing Intent | `axag-intent` not declared |
| `AXAG-002` | Missing Entity | `axag-entity` not declared |
| `AXAG-003` | Missing Action Type | `axag-action-type` not declared |
| `AXAG-004` | Invalid Action Type | Value not in allowed enum |
| `AXAG-005` | Invalid Risk Level | Value not in allowed enum |
| `AXAG-006` | Unsafe Mutation | Mutating action without risk declaration |
| `AXAG-007` | Missing Confirmation | High/critical risk without confirmation requirement |
| `AXAG-008` | Parameter Mismatch | Required parameters not matching input elements |
| `AXAG-009` | Scope Mismatch | Child scope less restrictive than parent |
| `AXAG-010` | Manifest Drift | Annotation changed without manifest regeneration |

## Runtime Error Codes

| Code | Name | Description |
|------|------|-------------|
| `AXAG-R001` | Precondition Not Met | Required precondition is false |
| `AXAG-R002` | Confirmation Rejected | User declined confirmation |
| `AXAG-R003` | Approval Pending | Awaiting required approvals |
| `AXAG-R004` | Rate Limited | Invocation frequency exceeded |
| `AXAG-R005` | Role Unauthorized | Invoking role not in required roles |

## Conformance Levels

Source: https://axag.org/docs/specification/conformance-levels

AXAG defines three conformance levels that represent progressive implementation maturity.

## Basic Conformance
**Minimum viable annotation.** Required fields: `axag-intent`, `axag-entity`, `axag-action-type`.

Suitable for: initial adoption, proof of concept, internal tooling.

## Intermediate Conformance
**Production-ready annotation.** Adds: `axag-required-parameters`, `axag-scope`, `axag-risk-level`, `axag-description`.

Suitable for: production deployments, external-facing products, agent-accessible interfaces.

## Full Conformance
**Enterprise-grade annotation.** Adds all applicable optional dimensions: preconditions, postconditions, side effects, confirmation, approval, idempotency, roles, rate limits.

Suitable for: regulated industries, high-trust agent interactions, enterprise standards compliance.

## Claiming Conformance
Every Semantic Manifest declares its conformance level in the `conformance` field. Generators compute it from the metadata the actions actually declare, so a claim can't exceed what the annotations support:
```json
{
  "version": "1.1.0",
  "conformance": "intermediate",
  "actions": []
}
```

The CLI's `axag validate --level` flag accepts the same names. The earlier `A`, `AA`, `AAA` names are still accepted and map to `basic`, `intermediate`, `full`.


# Semantic Manifest

## Semantic Manifest: What It Is

Source: https://axag.org/docs/semantic-manifest/what-it-is

The Semantic Manifest is a **structured JSON document** generated from AXAG annotations. It serves as the intermediate artifact between annotated UI elements and MCP tool definitions.

## Purpose

The manifest:
1. **Catalogs** all annotated operations in a structured format
2. **Normalizes** annotation data into a consistent schema
3. **Enables discovery** — agents query the manifest to find available operations
4. **Serves as input** for MCP tool generation
5. **Provides a validation target** for CI/CD pipelines

## Structure

```json title="axag-manifest.json — example structure" showLineNumbers
{
  "version": "1.1.0",
  "generated_at": "2026-09-14T00:00:00.000Z",
  "source": {
    "paths": ["src"],
    "tool": "axag-cli",
    "tool_version": "1.0.2"
  },
  "conformance": "intermediate",
  "actions": [
    {
      "intent": "product.search",
      "entity": "product",
      "action_type": "read",
      "operation_id": "product_search",
      "description": "Search the product catalog by text query with optional filters",
      "required_parameters": [
        { "name": "query", "type": "string" }
      ],
      "optional_parameters": [
        { "name": "category", "type": "string" },
        { "name": "price_min", "type": "string" },
        { "name": "price_max", "type": "string" }
      ],
      "risk_level": "none",
      "idempotent": true,
      "scope": "public",
      "source_file": "src/pages/search.html",
      "source_line": 1
    }
  ]
}
```

## Manifest vs Annotations

| Aspect | Annotations | Manifest |
|--------|------------|---------|
| Format | HTML attributes | JSON document |
| Location | Inline in UI code | Standalone file |
| Scope | Single element | Entire page/application |
| Consumer | Build tools, extractors | Agent runtimes, validators |
| Mutability | Changed by developers | Generated from annotations |

The manifest is a **derived artifact**. The annotations are the source of truth.

## Next Steps

- [Why It Exists](/docs/semantic-manifest/why-it-exists)
- [Manifest Schema](/docs/semantic-manifest/manifest-schema)

## Why the Semantic Manifest Exists

Source: https://axag.org/docs/semantic-manifest/why-it-exists

The manifest exists because AXAG annotations are scattered across HTML elements throughout an application. Agents need a single, queryable document to discover all available operations.

## Problems Without a Manifest
1. Agents would need to parse every page's DOM to find annotations
2. No consolidated view of available operations
3. No validation checkpoint between annotations and tool generation
4. No versioned artifact for change tracking

## The Manifest as Bridge
```
Annotations (scattered) → Manifest (consolidated) → Tools (consumable)
```

The manifest consolidates, normalizes, and structures all annotation data into a single document that agent runtimes and toolchains can consume efficiently.

## Manifest Schema

Source: https://axag.org/docs/semantic-manifest/manifest-schema

The Semantic Manifest is validated by a JSON Schema published at [`/schema/v1.1/axag-manifest.schema.json`](pathname:///schema/v1.1/axag-manifest.schema.json). The [v1 schema](pathname:///schema/v1/axag-manifest.schema.json) stays published for existing manifests; v1.1 only adds optional fields and enum values, so every valid v1 manifest is also valid under v1.1.

## Top-Level Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `version` | `string` (semver) | Yes | AXAG specification version |
| `generated_at` | `date-time` | Yes | ISO 8601 timestamp |
| `source` | `Source` | Yes | Where the annotations were read from |
| `conformance` | `enum` | Yes | `basic`, `intermediate`, `full` |
| `actions` | `Action[]` | Yes | Operation definitions |

## Source Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | `uri` | No | Application URL |
| `paths` | `string[]` | No | Source paths scanned |
| `tool` | `string` | No | Generator name |
| `tool_version` | `string` | No | Generator version |

## Action Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `intent` | `string` | Yes | Semantic intent, `entity.verb` (`^[a-z_]+\.[a-z_]+$`) |
| `entity` | `string` | Yes | Domain entity (`^[a-z_]+$`) |
| `action_type` | `enum` | Yes | `read`, `write`, `delete`, `navigate` |
| `description` | `string` | Yes | Human-readable description |
| `operation_id` | `string` | No | Unique operation identifier |
| `required_parameters` | `Parameter[]` | No | Parameters that must be provided |
| `optional_parameters` | `Parameter[]` | No | Parameters that may be provided |
| `risk_level` | `enum` | No | `none`, `low`, `medium`, `high`, `critical` |
| `confirmation_required` | `boolean` | No | Human confirmation gate |
| `approval_required` | `boolean` | No | Role-based approval gate |
| `approval_roles` | `string[]` | No | Roles that can approve |
| `idempotent` | `boolean` | No | Retry safety |
| `async` | `boolean` | No | Completes asynchronously (1.1) |
| `scope` | `enum` | No | `public`, `user`, `tenant`, `global` (`public` added in 1.1) |
| `tenant_boundary` | `enum` | No | `strict`, `relaxed` (1.1) |
| `required_roles` | `string[]` | No | Roles permitted to invoke (1.1) |
| `side_effects` | `string[]` | No | Observable changes |
| `preconditions` | `string[]` | No | Required state |
| `postconditions` | `string[]` | No | Guaranteed state |
| `element_selector` | `string` | No | CSS selector of the source element |
| `source_file` | `string` | No | File the annotation lives in |
| `source_line` | `integer` | No | Line in that file (1-based) |

## Parameter Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Parameter name |
| `type` | `enum` | Yes | `string`, `number`, `integer`, `boolean`, `array`, `object` (`integer` added in 1.1) |
| `description` | `string` | No | Human-readable description |
| `enum` | `array` | No | Allowed values |
| `min` / `max` | `number` | No | Numeric bounds |
| `minLength` / `maxLength` | `integer` | No | String length bounds (`minLength` added in 1.1) |
| `pattern` | `string` | No | Regular expression the value must match (1.1) |
| `format` | `enum` | No | `email`, `url`, `date`, `datetime`, `uuid` |
| `default` | any | No | Value used when omitted |
| `items` | `object` | No | JSON Schema for array elements (1.1) |
| `properties` | `object` | No | JSON Schema properties for objects (1.1) |
| `source` | `enum` | No | `harvested:html`, `zod`, `openapi` — where an undeclared parameter came from (1.1) |

Which optional fields a manifest fills in determines its [conformance level](/docs/specification/conformance-levels).

## Manifest Generation Model

Source: https://axag.org/docs/semantic-manifest/generation-model

Semantic Manifests are generated from AXAG annotations through extraction, normalization, and serialization.

## Generation Pipeline

```mermaid
graph LR
    A[Source Files] --> B[Annotation Extractor]
    B --> C[Normalization]
    C --> D[Validation]
    D --> E[Serialization]
    E --> F[manifest.json]
```

## Generation Approaches

### Build-Time Extraction (Recommended)
A bundler plugin reads source files (HTML, JSX, TSX, Vue SFC, Angular templates) and generates the manifest during the build. See [Build-Time Compilation](/docs/tool-generation/build-time-compilation).

### Runtime Extraction
A client-side script reads `axag-*` attributes from the live DOM. Useful for dynamic applications where annotations are computed at runtime.

### Static Analysis
An AST-based analyzer processes source files without rendering — `axag generate` in CI, using the same compiler as the bundler plugin. Most reliable for CI/CD validation.

Annotations whose value is only known at runtime (`axag={spec}` built from props) can't be extracted statically. Generators list them under `dynamic_actions` so a runtime knows the manifest is incomplete for that page.

## Extraction Rules
1. Scan all elements with any `axag-*` attribute
2. Group attributes by element
3. Resolve context inheritance from parent elements
4. Normalize parameter references
5. Validate required fields per conformance level
6. Serialize to manifest JSON

## Schema Harvesting

Source: https://axag.org/docs/semantic-manifest/schema-harvesting

An action's parameters don't have to be written out in `axag-*` attributes. Generators combine three sources, highest precedence first:

| Source | Where it comes from | `source` in the manifest |
|--------|---------------------|--------------------------|
| **Declared** | `axag-required-parameters` / `axag-optional-parameters`, `req=` / `opt=` in the macro | *(omitted)* |
| **Schema binding** | A Zod schema or OpenAPI operation named by `axag-schema` or the CLI's `bindings` config | `zod` or `openapi` |
| **Harvested** | The form's controls, constraints and labels | `harvested:html` |

## Precedence

1. A higher source decides whether a parameter is **required or optional** and keeps every field it sets.
2. Lower sources **fill fields the higher one left out**, such as a description from a `<label>` or `maxLength` from a schema.
3. A parameter declared **by name only** (`'["email"]'`) has no type of its own, so its type also comes from a lower source.
4. Parameters found only in a lower source are **added**.
5. A binding's `x-axag-risk-level` and summary are used only when the annotation declares no risk level or description.

## Which controls are harvested

The parameter scope of an annotated element is:

- the element itself, if it is a `<form>`;
- its form, if it is a submit button (`<button>` without `type`, `type="submit"`, or `<input type="submit|image">`), including a form linked with `form="id"`;
- the element named by `axag-params-from="#id"`.

Inside that scope, `<input>`, `<select>`, `<textarea>` and elements with a form-control role (`textbox`, `combobox`, `switch`, `checkbox`, `slider`, `spinbutton`) are harvested, plus controls elsewhere on the page with `form="<scope id>"`. Disabled controls and `hidden`, `file`, `submit`, `button`, `reset` and `image` inputs are skipped.

## HTML to parameter mapping

| Markup | Parameter |
|--------|-----------|
| `axag-parameter`, else `name`, else `id` | `name` (converted to snake_case) |
| `required`, `aria-required="true"` | listed in `required_parameters` |
| `type="number"` / `"range"`, `role="slider"` / `"spinbutton"` | `type: "integer"`, or `"number"` when `step` is fractional or `any` |
| `min`, `max` (`aria-valuemin`, `aria-valuemax`) | `min`, `max` |
| `type="email"` / `"url"` / `"date"` / `"datetime-local"` | `format: "email"` / `"url"` / `"date"` / `"datetime"` |
| `minlength`, `maxlength`, `pattern` | `minLength`, `maxLength`, `pattern` |
| `<select>` options | `enum` |
| `<select multiple>` | `type: "array"`, `items.enum` |
| Radio buttons sharing a `name` | `enum` of their values |
| Single checkbox, `role="switch"` | `type: "boolean"` |
| Checkboxes sharing a `name` | `type: "array"`, `items.enum` |
| `aria-labelledby`, `aria-label`, `<label for>`, wrapping `<label>` | `description` |
| Group `<legend>` or `role="radiogroup"` label | `description` of a radio or checkbox group |
| `aria-describedby` | appended to `description` |
| `axag-parameter-type`, `-required`, `-description`, `-format`, `-enum`, `-min`, `-max`, `-min-length`, `-max-length`, `-pattern` | override the harvested value |

JSX spellings (`htmlFor`, `maxLength`, `minLength`) read the same as HTML. JSX expressions such as `required={isRequired}` are dynamic and are ignored.

## Schema bindings

```html title="Inline binding"
<form axag="write:user.invite!medium" axag-schema="zod:./src/schemas/user.ts#InviteUser">…</form>
```

| Ref | Meaning |
|-----|---------|
| `zod:<file>#<export>` | A Zod 4 `z.object()` export; `#<export>` defaults to `default` |
| `openapi:<file>#<operationId>` | Path and query parameters plus the JSON request body of an operation |
| `openapi:<operationId>` | Same, using the `openapi` document set in the CLI config |

See [Bind Zod or OpenAPI Schemas](/docs/tutorials/bind-schemas).

## Related lint rules

| Rule | Checks |
|------|--------|
| AXAG-LINT-029 | A submitted control has no name, so agents can't fill it |
| AXAG-LINT-030 | The form disagrees with a schema-sourced parameter in the manifest (required, type or enum) |
| AXAG-LINT-031 | An annotated button, link or control has no accessible name |
| AXAG-LINT-032 | A harvested parameter has no label or description |

To turn harvesting off, run `axag scan … --no-harvest`.

## Manifest Discovery Model

Source: https://axag.org/docs/semantic-manifest/discovery-model

Agent runtimes discover manifests through well-known URLs or service registries.

## Discovery Mechanisms

### Well-Known URL
```
https://example.com/.well-known/axag-manifest.json
```

### HTTP Header
```
Link: </.well-known/axag-manifest.json>; rel="axag-manifest"
```

### Meta Tag
```html
<meta name="axag-manifest" content="/axag-manifest.json" />
```

### Service Registry
For microservice architectures, manifests can be registered in a central manifest registry.

## Discovery Flow
1. Agent navigates to a domain
2. Agent checks for well-known URL, HTTP header, or meta tag
3. Agent fetches the manifest
4. Agent indexes available operations
5. Agent generates or consumes tool definitions

## Execution Planning Role

Source: https://axag.org/docs/semantic-manifest/execution-planning-role

The manifest enables agent runtimes to plan multi-step workflows by analyzing operation preconditions and postconditions.

## Workflow Planning

Given operations with declared pre/postconditions, an agent can automatically determine execution order:

```
validate_cart       → post: cart_validated
reserve_inventory   → pre: cart_validated → post: inventory_reserved
checkout_begin      → pre: cart_validated, inventory_reserved → post: checkout_session_created
process_payment     → pre: checkout_session_created → post: payment_processed
confirm_order       → pre: payment_processed → post: order_confirmed
```

The agent constructs a dependency graph and executes operations in the correct sequence.

## Conflict Detection
The manifest also enables agents to detect conflicting operations — for example, two operations that both modify the same entity with incompatible postconditions.

## Manifest Field Reference

Source: https://axag.org/docs/semantic-manifest/field-reference

Complete reference for all manifest fields. See [Manifest Schema](/docs/semantic-manifest/manifest-schema) for the structural overview.

For each field, this reference provides: name, type, required status, description, constraints, and examples.

Refer to the [Full Schema Reference](/docs/reference/schema-reference) for the canonical JSON Schema document.

## Manifest Validation

Source: https://axag.org/docs/semantic-manifest/manifest-validation

Manifests MUST be validated before consumption by agent runtimes.

## Validation Checks

1. **Schema conformance** — Manifest matches the expected JSON schema
2. **Required field presence** — All required fields for the declared conformance level are present
3. **Value validity** — Enum values are from the allowed set
4. **Parameter consistency** — Required parameters have definitions
5. **Safety consistency** — High/critical risk operations have confirmation requirements
6. **Drift detection** — Manifest matches current annotation source (when possible)

## Validation in CI

```yaml
# Example CI step
- name: Validate AXAG Manifest
  run: npx axag validate src --level intermediate --strict
```

## Common Validation Failures

| Failure | Cause | Fix |
|---------|-------|-----|
| Missing required fields | Annotations incomplete | Add missing `axag-*` attributes |
| Invalid enum value | Typo in action type or risk level | Use values from canonical vocabulary |
| Parameter mismatch | Manifest lists parameters not in annotations | Regenerate manifest from source |
| Safety violation | High-risk mutation without confirmation | Add `axag-confirmation-required="true"` |


# MCP Tool Generation

## Tool Generation Mapping Rules

Source: https://axag.org/docs/tool-generation/mapping-rules

This section defines the rules for transforming Semantic Manifest operations into MCP-compatible tool definitions.

## Core Mapping

| Manifest Field | MCP Tool Field | Transformation |
|---------------|---------------|----------------|
| `intent` | `name` | `.` → `_` |
| `description` | `description` | Direct mapping |
| `required_parameters`, `optional_parameters` | `input_schema.properties` | Transform to JSON Schema |
| `required_parameters[].name` | `input_schema.required` | Collect names |
| `action_type` | `metadata.action_type` | Direct mapping |
| `risk_level` | `metadata.risk_level` | Direct mapping |
| `confirmation_required` | `metadata.confirmation_required` | Direct mapping |
| `idempotent` | `metadata.idempotent` | Direct mapping |

The full table, including scope, roles and conditions, is in the [Tool Mapping Rules Reference](/docs/reference/tool-mapping-rules).

## Parameter Transformation

Manifest parameters transform to JSON Schema properties:

**Manifest parameter:**
```json title="Manifest parameter definition"
{ "required_parameters": [{ "name": "cart_id", "type": "string", "description": "The cart identifier" }] }
```

**Generated JSON Schema property:**
```json title="Generated JSON Schema"
{ "cart_id": { "type": "string", "description": "The cart identifier" } }
```

> `"cart_id"` is added to the `"required"` array of the generated `input_schema` because it is a required parameter.

## Tool Name Generation

Tool names are derived from the `intent` field by replacing `.` with `_`:
- `product.search` → `product_search`
- `checkout.begin` → `checkout_begin`

## Complete Example

**Manifest Operation:**
```json title="Semantic Manifest — product.search" showLineNumbers
{
  "intent": "product.search",
  "entity": "product",
  "action_type": "read",
  "operation_id": "product_search",
  "description": "Search the product catalog",
  "required_parameters": [{ "name": "query", "type": "string", "description": "Search query" }],
  "optional_parameters": [
    { "name": "category", "type": "string", "description": "Category filter" }
  ],
  "risk_level": "none",
  "idempotent": true,
  "scope": "public"
}
```

**Generated MCP Tool:**
```json title="Generated MCP tool — product_search" showLineNumbers
{
  "name": "product_search",
  "description": "Search the product catalog",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search query" },
      "category": { "type": "string", "description": "Category filter" }
    },
    "required": ["query"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "product.search",
    "source_entity": "product"
  }
}
```

## Next Steps

- [Tool Signatures](/docs/tool-generation/tool-signatures)
- [Generated Examples](/docs/tool-generation/generated-examples)

## Tool Signatures

Source: https://axag.org/docs/tool-generation/tool-signatures

Each MCP tool has a signature consisting of: name, description, input schema, and safety metadata.

## Signature Components

```json title="MCP tool signature — product_search" showLineNumbers
{
  "name": "product_search",
  "description": "Search the product catalogue",
  "input_schema": {
    "type": "object",
    "properties": { "query": { "type": "string", "description": "Search query" } },
    "required": ["query"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "product.search",
    "source_entity": "product"
  }
}
```

## Naming Conventions
- Tool names MUST be unique within a tool registry
- Tool names SHOULD use snake_case
- Tool names SHOULD be verb_noun or noun_verb format

## Input Schema Translation

Source: https://axag.org/docs/tool-generation/input-schema-translation

Manifest parameters translate to JSON Schema within the MCP tool's `input_schema`.

## Type Mapping

| AXAG Parameter Type | JSON Schema Type |
|--------------------|-----------------|
| `string` | `"type": "string"` |
| `number` | `"type": "number"` |
| `boolean` | `"type": "boolean"` |
| `date` | `"type": "string", "format": "date"` |
| `datetime` | `"type": "string", "format": "date-time"` |
| `enum` | `"type": "string", "enum": [...]` |
| `array` | `"type": "array", "items": {...}` |
| `object` | `"type": "object", "properties": {...}` |

## Constraint Translation

| AXAG Constraint | JSON Schema |
|----------------|-------------|
| `min` | `"minimum"` |
| `max` | `"maximum"` |
| `min_length` | `"minLength"` |
| `max_length` | `"maxLength"` |
| `pattern` | `"pattern"` |
| `format` | `"format"` |
| `enum` | `"enum"` |

## Constraints and Safety Translation

Source: https://axag.org/docs/tool-generation/constraints-safety-translation

Safety metadata from the manifest translates to the tool's `metadata` object, enabling agent runtimes to enforce guardrails.

## Metadata Object
```json title="Tool metadata — high-risk write operation" showLineNumbers
{
  "metadata": {
    "action_type": "write",
    "risk_level": "high",
    "idempotent": false,
    "confirmation_required": true,
    "approval_required": false,
    "preconditions": ["cart_validated", "inventory_reserved"],
    "postconditions": ["checkout_session_created"],
    "side_effects": ["inventory_locked", "payment_hold_created"],
    "source_intent": "checkout.begin",
    "source_entity": "order"
  }
}
```

## Agent Runtime Enforcement

Agent runtimes consuming tools with safety metadata SHOULD:
1. Check preconditions before invocation
2. Request confirmation for operations where `confirmation_required` is true
3. Submit approval requests where `approval_required` is true
4. Respect rate limits enforced by the server (`axag-rate-limit` is advisory and not carried into the manifest)
5. Log side effects for audit trails

## Authorization and Identity

Source: https://axag.org/docs/tool-generation/authorization-identity

Tool definitions carry role and tenant context from AXAG annotations, enabling agent runtimes to enforce access control.

## Role-Based Access
`axag-required-roles` becomes `metadata.required_roles`:
```json title="Role-based access control — tool metadata excerpt"
{
  "name": "user_delete",
  "metadata": {
    "action_type": "delete",
    "risk_level": "high",
    "required_roles": ["admin", "super_admin"],
    "source_intent": "user.delete",
    "source_entity": "user"
  }
}
```

## Tenant Isolation
`axag-scope` and `axag-tenant-boundary` become `metadata.scope` and `metadata.tenant_boundary`:
```json title="Tenant isolation — tool metadata excerpt"
{
  "name": "settings_update",
  "metadata": {
    "action_type": "write",
    "risk_level": "medium",
    "scope": "tenant",
    "tenant_boundary": "strict",
    "source_intent": "settings.update",
    "source_entity": "settings"
  }
}
```

Agent runtimes MUST validate the invoking identity's roles and tenant context before executing tools with access control metadata.

## Build-Time Compilation

Source: https://axag.org/docs/tool-generation/build-time-compilation

A bundler plugin reads annotations while your app builds, so the manifest and the agent-facing tools are produced from the same sources, at the same moment, as the code that ships.

```bash
npm install -D @axag/compiler
```

```ts title="vite.config.ts"

```

The plugin is built on [unplugin](https://github.com/unjs/unplugin), so the same implementation ships for Vite, Rollup, webpack, Rspack and esbuild — import from `@axag/compiler/webpack`, `/rollup`, `/rspack` or `/esbuild`.

## What a build produces

| Output | Purpose |
|--------|---------|
| `.well-known/axag-manifest.json` | The Semantic Manifest, at the [discovery](/docs/semantic-manifest/discovery-model) location |
| `axag-tools.webmcp.json` | The same actions as WebMCP tool definitions |
| `virtual:axag/tools` | A module your app imports to register the tools |

```ts title="src/agent.ts"

```

Nothing from the compiler ends up in your bundle: the parsers run at build time, and what reaches the browser is the JSON it produced.

In dev, Vite serves both files from memory and recompiles when an annotated file changes.

## Sources it reads

| Source | Notes |
|--------|-------|
| `.html`, `.htm` | Plain HTML |
| `.jsx`, `.tsx` | Attributes, and `axag={spec}` objects |
| `.vue` | The `<template>` block |
| `*.component.html` | Angular templates |

## Action specs

Components can carry the annotation as an object instead of a string. `defineAction` is an identity function — it exists so the value has a name the compiler recognises:

```tsx title="src/admin/actions.ts"

  intent: 'user.deactivate',
  actionType: 'write',
  riskLevel: 'critical',
  confirmationRequired: true,
  approvalRoles: ['security_admin'],
  requiredParameters: [{ name: 'user_id', type: 'string', format: 'uuid' }],
  handler: async ({ user_id }) => api.deactivate(user_id),
});
```

```tsx
<button axag={deactivateUser}>Deactivate</button>
```

The compiler reads a spec when it is a module-level `const` or a `defineAction({...})` call, in that file or one it imports with a relative path. The `handler` is ignored: it belongs to the runtime, not the manifest.

## Dynamic actions

A value the compiler can't read — a prop, something built at runtime — can't appear in the manifest, because its intent isn't known until the page runs. Those elements are listed instead:

```json title="axag-manifest.json"
{
  "actions": [],
  "dynamic_actions": [
    { "source_file": "src/Admin.tsx", "source_line": 16, "reason": "<button> has a dynamic axag value that could not be read at build time" }
  ]
}
```

A runtime reading this manifest knows the list of actions is incomplete for that page. `axag-lint` reports the same elements as **AXAG-LINT-033** (info), so you can find them without reading the manifest.

## In CI

Without a bundler, the CLI runs the same compiler:

```bash
npx axag generate src --manifest public/.well-known/axag-manifest.json --validate
```

## Next Steps

- [Tool Registry Generation](/docs/tool-generation/tool-registry-generation)
- [Runtime Consumption Patterns](/docs/tool-generation/runtime-consumption-patterns)

## Tool Registry Generation

Source: https://axag.org/docs/tool-generation/tool-registry-generation

The Tool Registry is a collection of all MCP tool definitions generated from the Semantic Manifest.

## Registry Structure
```json title="Tool registry structure"
{
  "schema_version": "1.0.0",
  "generated_at": "2026-03-14T10:00:00.000Z",
  "source_manifest": "axag-manifest.json",
  "tools": [
    { "name": "product_search", "description": "…", "input_schema": {}, "metadata": {} },
    { "name": "cart_add_item", "description": "…", "input_schema": {}, "metadata": {} },
    { "name": "checkout_begin", "description": "…", "input_schema": {}, "metadata": {} }
  ]
}
```

## Generation Pipeline
```mermaid
graph LR
    A[Semantic Manifest] --> B[Tool Generator]
    B --> C[Tool Registry JSON]
    C --> D[MCP Server]
    D --> E[Agent Runtime]
```

## Serving the Registry
- Static JSON file served at a well-known endpoint
- MCP server that dynamically resolves tools from the manifest
- API endpoint that returns tool definitions on demand

## Generated Tool Examples

Source: https://axag.org/docs/tool-generation/generated-examples

## Example 1: Product Search (Read)
```json title="product_search — Read / No Risk"
{
  "name": "product_search",
  "description": "Search the product catalog by text query with optional filters",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search query text" },
      "category": { "type": "string", "description": "Category filter" },
      "price_min": { "type": "number", "minimum": 0, "description": "Minimum price" },
      "price_max": { "type": "number", "minimum": 0, "description": "Maximum price" },
      "sort_by": {
        "type": "string",
        "enum": ["relevance", "price_asc", "price_desc", "newest"],
        "description": "Sort order"
      }
    },
    "required": ["query"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "product.search",
    "source_entity": "product"
  }
}
```

## Example 2: Cart Add Item (Write)
```json title="cart_add_item — Write / Low Risk"
{
  "name": "cart_add_item",
  "description": "Add a product to the shopping cart",
  "input_schema": {
    "type": "object",
    "properties": {
      "product_id": { "type": "string", "description": "Product identifier" },
      "quantity": {
        "type": "number",
        "minimum": 1,
        "maximum": 99,
        "description": "Quantity to add"
      },
      "variant_id": { "type": "string", "description": "Product variant (size, color)" }
    },
    "required": ["product_id", "quantity"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "low",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "cart.add_item",
    "source_entity": "cart"
  }
}
```

## Example 3: Begin Checkout (Write, High Risk)
```json title="checkout_begin — Write / High Risk ⚠️" showLineNumbers
{
  "name": "checkout_begin",
  "description": "Start checkout for a validated cart and create a checkout session",
  "input_schema": {
    "type": "object",
    "properties": {
      "cart_id": { "type": "string" },
      "payment_method_id": { "type": "string" },
      "shipping_address_id": { "type": "string" }
    },
    "required": ["cart_id", "payment_method_id", "shipping_address_id"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "high",
    "idempotent": false,
    "confirmation_required": true,
    "approval_required": false,
    "side_effects": ["inventory_locked", "payment_hold_created"],
    "preconditions": ["cart_validated", "inventory_reserved"],
    "postconditions": ["checkout_session_created"],
    "source_intent": "checkout.begin",
    "source_entity": "order"
  }
}
```

## Example 4: Account Delete (Critical)
```json title="account_delete — Delete / Critical Risk 🔴" showLineNumbers
{
  "name": "account_delete",
  "description": "Permanently delete user account and all associated data",
  "input_schema": {
    "type": "object",
    "properties": {
      "account_id": { "type": "string" },
      "confirmation_code": { "type": "string", "description": "User-provided confirmation code" }
    },
    "required": ["account_id", "confirmation_code"]
  },
  "metadata": {
    "action_type": "delete",
    "risk_level": "critical",
    "idempotent": false,
    "confirmation_required": true,
    "approval_required": true,
    "approval_roles": ["admin"],
    "side_effects": ["data_purged", "subscriptions_cancelled", "audit_log_created"],
    "source_intent": "account.delete",
    "source_entity": "account"
  }
}
```

## Example 5: Lead Create (CRM)
```json title="lead_create — CRM / Low Risk"
{
  "name": "lead_create",
  "description": "Create a new sales lead in the CRM",
  "input_schema": {
    "type": "object",
    "properties": {
      "first_name": { "type": "string" },
      "last_name": { "type": "string" },
      "email": { "type": "string", "format": "email" },
      "company": { "type": "string" },
      "source": { "type": "string", "enum": ["web", "referral", "event", "cold_call"] }
    },
    "required": ["first_name", "last_name", "email"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "low",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "lead.create",
    "source_entity": "lead"
  }
}
```

## Example 6: Campaign Schedule (Marketing)
```json title="campaign_schedule — Marketing / Medium Risk"
{
  "name": "campaign_schedule",
  "description": "Schedule a marketing campaign for future delivery",
  "input_schema": {
    "type": "object",
    "properties": {
      "campaign_id": { "type": "string" },
      "scheduled_at": { "type": "string", "format": "date-time" },
      "timezone": { "type": "string" }
    },
    "required": ["campaign_id", "scheduled_at"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "medium",
    "idempotent": true,
    "confirmation_required": true,
    "approval_required": false,
    "preconditions": ["campaign_approved", "audience_configured"],
    "source_intent": "campaign.schedule",
    "source_entity": "campaign"
  }
}
```

## Example 7: Ticket Escalate (Support)
```json title="ticket_escalate — Support / Medium Risk"
{
  "name": "ticket_escalate",
  "description": "Escalate a support ticket to a higher tier",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticket_id": { "type": "string" },
      "escalation_reason": { "type": "string" },
      "target_tier": { "type": "string", "enum": ["tier_2", "tier_3", "manager"] }
    },
    "required": ["ticket_id", "escalation_reason", "target_tier"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "medium",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "side_effects": ["notification_sent", "sla_timer_reset"],
    "source_intent": "ticket.escalate",
    "source_entity": "ticket"
  }
}
```

## Example 8: Report Generate (Analytics)
```json title="report_generate — Analytics / No Risk"
{
  "name": "report_generate",
  "description": "Generate an analytics report with specified parameters",
  "input_schema": {
    "type": "object",
    "properties": {
      "report_type": { "type": "string", "enum": ["revenue", "engagement", "retention", "funnel"] },
      "date_from": { "type": "string", "format": "date" },
      "date_to": { "type": "string", "format": "date" },
      "dimensions": { "type": "array", "items": { "type": "string" } },
      "format": { "type": "string", "enum": ["json", "csv", "pdf"] }
    },
    "required": ["report_type", "date_from", "date_to"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "report.generate",
    "source_entity": "report"
  }
}
```

## Example 9: Booking Cancel (Travel)
```json title="booking_cancel — Travel / High Risk ⚠️"
{
  "name": "booking_cancel",
  "description": "Cancel an existing travel booking",
  "input_schema": {
    "type": "object",
    "properties": {
      "booking_id": { "type": "string" },
      "cancellation_reason": { "type": "string" }
    },
    "required": ["booking_id"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "high",
    "idempotent": true,
    "confirmation_required": true,
    "approval_required": false,
    "side_effects": ["refund_initiated", "inventory_released", "confirmation_email_sent"],
    "source_intent": "booking.cancel",
    "source_entity": "booking"
  }
}
```

## Example 10: Interview Schedule (Jobs)
```json title="interview_schedule — Jobs / Low Risk"
{
  "name": "interview_schedule",
  "description": "Schedule a job interview for a candidate",
  "input_schema": {
    "type": "object",
    "properties": {
      "candidate_id": { "type": "string" },
      "job_id": { "type": "string" },
      "interviewer_ids": { "type": "array", "items": { "type": "string" } },
      "scheduled_at": { "type": "string", "format": "date-time" },
      "duration_minutes": { "type": "number", "minimum": 15, "maximum": 240 }
    },
    "required": ["candidate_id", "job_id", "scheduled_at", "duration_minutes"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "low",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "side_effects": ["calendar_invites_sent", "candidate_notified"],
    "source_intent": "interview.schedule",
    "source_entity": "interview"
  }
}
```

## Runtime Consumption Patterns

Source: https://axag.org/docs/tool-generation/runtime-consumption-patterns

Agent runtimes consume MCP tool registries through standard patterns.

## Registration Lifecycle

A page's tools are not a fixed list. What an agent may invoke depends on the route, the user's role and what is on screen, so registration is scoped to the UI that owns each action:

1. Register with an `AbortSignal` belonging to the component, route or dialog
2. Abort it when that UI goes away — WebMCP has no `unregisterTool`
3. Unregister an action whose control becomes disabled, hidden, inert or detached
4. Register it again when the control becomes operable

See [Agent Runtime](/docs/frameworks/runtime) for the implementation, and [Visibility vs Operability](/docs/concepts/visibility-vs-operability) for why this matters: a tool that outlives its control promises something the UI is refusing.

## Discovery Pattern
1. Fetch tool registry from known endpoint
2. Index tools by name, entity, and action type
3. Cache registry with TTL based on `generated_at` timestamp

## Selection Pattern
1. Parse user intent
2. Match against available tool descriptions
3. Rank by relevance
4. Select best matching tool

## Invocation Pattern
1. Validate parameters against `input_schema`
2. Check preconditions from `metadata`
3. Request confirmation if `confirmation_required` — enforced on the server as well, since an agent in the page can bypass client checks
4. Submit approval if `approval_required`
5. Execute tool
6. Validate postconditions
7. Return results

## Error Handling Pattern
1. Parameter validation failure → report missing/invalid parameters
2. Precondition failure → report unmet preconditions
3. Confirmation rejected → abort
4. Rate limited → retry with backoff
5. Execution failure → report error with code


# Frameworks

## Agent Runtime

Source: https://axag.org/docs/frameworks/runtime

A manifest tells an agent what a page *can* do. The runtime tells it what the page can do **right now** — which actions are on screen, enabled, and permitted for this user.

```bash
npm install @axag/webmcp
```

## Registration follows the UI

```ts

const route = new AbortController();
registerManifest(tools, { signal: route.signal, handlers });

// Leaving the route takes its tools with it.
route.abort();
```

The `AbortSignal` is the whole lifecycle: [WebMCP](https://github.com/webmachinelearning/webmcp) has no `unregisterTool`, and aborting the signal you registered with is how a tool goes away. Tie that signal to whatever owns the action — a component, a route, a dialog — and the agent's list can't drift from the screen.

:::note Why not register everything at startup
The earlier `provideContext()` call was removed from the specification in March 2026 because it encouraged registering every tool up front, leaving ghost tools pointing at UI that had since unmounted. Registration scoped to a signal is the replacement.
:::

## Visibility and operability

AXAG distinguishes [visibility from operability](/docs/concepts/visibility-vs-operability). The runtime enforces it: an action is unregistered while its element is

- disabled (including through a disabled `<fieldset>`),
- `hidden`, `inert`, `aria-hidden="true"` or `aria-disabled="true"`,
- or no longer in the document,

and registered again when the element becomes operable. One `MutationObserver` serves every registration on the page.

This is what keeps an agent from being offered a button a person couldn't press.

## Executing an action

Without a handler, the runtime does what a person would: it fills the form the annotation points at using the tool's arguments, then presses the control.

- Parameters are matched by the name in the manifest, so `display_name` finds `displayName`.
- Values are assigned through the prototype setter, so React and Vue notice the change.
- Checkboxes, radio groups and multi-selects are set by value.

Pass a `handler` to call your own code instead.

## Middleware

```ts
registerManifest(tools, {
  signal: route.signal,
  middleware: [requireConfirmation, withTenantScope, auditLog],
});
```

Middleware wraps every invocation, in order, and can refuse the call. Safety enforcement belongs here rather than inside each handler.

:::warning Client-side checks are not enforcement
An agent running in the page can call your API directly. Middleware improves what the agent does; the server still has to enforce confirmation, approval and tenant boundaries.
:::

## Pages without a build step

```ts

registerDocument({ signal: controller.signal });
```

Reads the annotated elements on the page, harvesting parameters from their forms. Costs a DOM scan; prefer `registerManifest` with build-time tools where you have a bundler.

## Browser support

The runtime uses `document.modelContext`, falling back to `navigator.modelContext` (deprecated in Chromium 150). Where neither exists, registration reports through `onError` instead of throwing, so a page that annotates for agents still works for people.

## Framework bindings

| Framework | Package | Reach for |
|-----------|---------|-----------|
| React | [`@axag/react`](/docs/frameworks/react) | `useAxag`, `` |
| Vue | [`@axag/vue`](/docs/frameworks/vue) | `useAxag`, `v-axag` |
| Angular | [`@axag/angular`](/docs/frameworks/angular) | `[axag]` directive |

## React

Source: https://axag.org/docs/frameworks/react

```bash
npm install @axag/react
```

```tsx

const deactivateUser = defineAction({
  intent: 'user.deactivate',
  actionType: 'write',
  riskLevel: 'critical',
  confirmationRequired: true,
  requiredParameters: [{ name: 'user_id', type: 'string', format: 'uuid' }],
});

  const axag = useAxag(deactivateUser, { handler: () => api.deactivate(userId) });
  return <button {...axag}>Deactivate</button>;
}
```

The hook returns the `axag-*` attributes and a ref. Spreading them puts the annotation in the DOM — where the [DevTools extension](https://axag.org) and any other reader can see it — and registers the action while the component is mounted.

## Options

| Option | Description |
|--------|-------------|
| `handler` | What the tool does. Without one, the element's form is filled and the control is pressed |
| `middleware` | Wraps every call |
| `enabled` | `false` keeps the action off the agent's list, e.g. by role |
| `onError` | Registration failures, including browsers without WebMCP |

## Components you don't own

```tsx

  Deactivate

```

Renders a `display: contents` span, so it changes no layout. `as` renders a different element.

## Behaviour worth knowing

- **StrictMode is safe.** Each mount gets its own `AbortController`; the double mount registers, unregisters and registers again cleanly.
- **Re-registration is by annotation, not by render.** Changing `riskLevel` re-registers; re-rendering with the same spec doesn't.
- **Unmounting unregisters**, so conditional rendering and route changes keep the agent's tools in step with the screen.

## Build-time extraction

A spec held in a module-level `const` is also read by [`@axag/compiler`](/docs/tool-generation/build-time-compilation) at build time, so the same action appears in the manifest without running the app. A spec built from props can't be, and is listed under `dynamic_actions`.

## Vue

Source: https://axag.org/docs/frameworks/vue

```bash
npm install @axag/vue
```

## Composable

```vue
<script setup lang="ts">

const addItem = defineAction({
  intent: 'cart.add_item',
  actionType: 'write',
  riskLevel: 'low',
  requiredParameters: [{ name: 'product_id', type: 'string' }],
});

const { el, attrs } = useAxag(addItem, { handler: ({ product_id }) => cart.add(product_id) });
</script>

<template>
  <button ref="el" v-bind="attrs">Add to cart</button>
</template>
```

`enabled` takes a ref or getter, so an action can follow a permission check:

```ts
const { el, attrs } = useAxag(addItem, { enabled: () => user.canOrder });
```

Registration is undone by `onScopeDispose`, so unmounting or leaving a route removes the tool.

## Directive

```ts

app.use(AxagPlugin);
```

```vue
<button v-axag="addItem">Add to cart</button>
<button v-axag="{ spec: addItem, handler: add }">Add to cart</button>
```

The directive writes the `axag-*` attributes onto the element and registers the action, re-registering when the value changes.

## Templates are read at build time too

[`@axag/compiler`](/docs/tool-generation/build-time-compilation) reads `<template>` blocks in `.vue` files, so a static `axag="write:cart.add_item!low"` appears in the manifest. A bound `:axag="spec"` is only known at runtime and is listed under `dynamic_actions`.

## Angular

Source: https://axag.org/docs/frameworks/angular

```bash
npm install @axag/angular
```

```ts

@Component({
  standalone: true,
  imports: [AxagDirective],
  template: `<button [axag]="deactivateUser" [axagHandler]="deactivate">Deactivate</button>`,
})

  deactivateUser = defineAction({
    intent: 'user.deactivate',
    actionType: 'write',
    riskLevel: 'critical',
    approvalRequired: true,
    approvalRoles: ['security_admin'],
    requiredParameters: [{ name: 'user_id', type: 'string', format: 'uuid' }],
  });

  deactivate = ({ user_id }: { user_id: string }) => this.api.deactivate(user_id);
}
```

## Inputs

| Input | Description |
|-------|-------------|
| `axag` | The action spec (required) |
| `axagHandler` | What the tool does; defaults to filling the form and pressing the control |
| `axagMiddleware` | Wraps every call |
| `axagEnabled` | `false` keeps the action off the agent's list |

## Behaviour worth knowing

- **Routing and `@if` unregister the action**, because destroying the directive aborts its signal.
- **Changing an input re-registers** rather than adding a second tool.
- **SSR is a no-op**: on the server there is no model context to register with, and nothing to drive.
- The directive is standalone and works with Angular 16+.

## Templates are read at build time too

[`@axag/compiler`](/docs/tool-generation/build-time-compilation) reads `*.component.html` templates, so a static `axag="write:user.deactivate!critical"` appears in the manifest. A bound `[axag]="spec"` is known only at runtime and is listed under `dynamic_actions`.

## Safety Enforcers

Source: https://axag.org/docs/frameworks/safety

An annotation that says `risk-level="critical"` and `confirmation-required="true"` is a promise. Two pieces keep it: middleware in the page, so a cooperative agent behaves and a person gets the chance to refuse; and checks on the server, so the promise holds even when the agent doesn't cooperate.

:::warning The client half is not enforcement
An agent running in the page holds the page's credentials. It can skip the dialog and call your API directly. Client middleware improves what an agent does; only the server decides what it may do.
:::

## In the page

```ts

const safety = createEnforcers({
  confirm: { from: 'high', endpoint: '/axag/confirm' },
  tenant: { id: () => session.tenantId },
  csrf: {},
  audit: event => analytics.track('agent_action', event),
});

registerManifest(tools, { signal: route.signal, handlers, ...safety });
```

| Enforcer | What it does |
|----------|--------------|
| `confirm` | Shows the action and its parameters, read-only, in a closed shadow root the page cannot script. Declining refuses the call with `AXAG_CONFIRMATION_MISSING`. With `endpoint`, the answer is exchanged for a single-use token the server can check. |
| `tenant` | Removes tenant parameters from the agent-facing schema — an agent can't choose a tenant — and attaches the session's tenant instead. |
| `csrf` | Attaches the token from `<meta name="csrf-token">`. |
| `audit` | Records every call with its outcome, and **parameter names only**. |

What the enforcers add travels in a reserved `_axag` entry beside the agent's parameters, so a handler can forward it:

```ts

const handler = input =>
  fetch('/api/users/deactivate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', ...axagHeaders(input) },
    body: JSON.stringify(withoutEnvelope(input)),
  });
```

## On the server

```ts

const enforcer = createEnforcer({
  manifest,
  approvals: ({ action, actor }) => approvals.exists(action.intent, actor.id),
  csrfOf: request => request.session.csrfToken,
  audit: record => log.info(record),
});

const actorOf = req => ({ id: req.session.userId, tenant: req.session.tenant, roles: req.session.roles });

app.post('/axag/confirm', express.json(), axagConfirmRoute(enforcer, { actorOf }));
app.use('/api', express.json(), axagGuard(enforcer, { actorOf }));
```

Enforcement follows the generated manifest, not anything the caller sent:

| Declared | Checked |
|----------|---------|
| `risk_level` ≥ `high`, or `confirmation_required` | A confirmation token bound to this intent, these parameters and this person; single use; expires |
| `approval_required` | Your `approvals` hook grants it, with `approval_roles` in hand |
| `required_roles` | The actor holds one |
| `scope: "tenant"` | The session has a tenant; a claimed tenant matches; under `tenant_boundary: "strict"`, no parameter points elsewhere |

Refusals carry the codes from [Error Codes](/docs/reference/error-codes) — `AXAG_CONFIRMATION_MISSING` (428), `AXAG_TENANT_BOUNDARY` (403), `AXAG_ROLE_INSUFFICIENT` (403) — so the same refusal reads the same way in the page, in the manifest and in your logs.

Any framework works: `enforcer.check({ intent, parameters, headers, actor })` throws an `AxagError` with the code and status. The Express adapter is a convenience over that one call.

## Confirmation tokens

A token proves a person saw this action with these parameters and agreed:

1. The page asks `POST /axag/confirm` after the person confirms.
2. The server binds a token to the intent, a hash of the parameters and the actor, with a short expiry.
3. The call carries it as `X-AXAG-Confirmation`.
4. The server consumes it once. Replaying it, changing a parameter, or using someone else's is refused.

`MemoryConfirmationStore` suits a single process. Across several, implement `ConfirmationStore` — `issue` and `consume` — over Redis or your database.

## Checking your coverage

```ts
writeFileSync('axag-enforced.json', JSON.stringify({ intents: enforcer.enforcedIntents() }));
```

With `enforcedIntentsPath` set in `.axaglintrc.json`, **AXAG-LINT-037** warns about any high-risk action the server isn't enforcing, and **AXAG-LINT-036** flags a tenant-scoped action that still takes the tenant as a parameter.

## Browsers Without WebMCP

Source: https://axag.org/docs/frameworks/bridge

WebMCP is a draft. Annotating a page for agents shouldn't wait for it to ship everywhere, so two small pieces cover the gap: a registry where the browser has none, and a relay that connects a tab to agents that live outside it.

## The shim

```bash
npm install @axag/shim
```

```ts

installShim(); // does nothing where the browser has its own implementation
```

It implements the part of the draft a page calls — `registerTool(tool, { signal })`, with abort unregistering — so [`@axag/webmcp`](/docs/frameworks/runtime) and the framework bindings work unchanged. Under 2 KB gzipped, no dependencies.

Installing it connects no agent. It is the socket a connection plugs into.

## The bridge

```bash
npx axag-bridge --origin https://app.example.com
```

```text
[axag-bridge] listening on ws://127.0.0.1:53422
[axag-bridge] pairing code: 7f3a91c2
```

```ts

connectBridge({ url: 'ws://127.0.0.1:53422', pairingCode: '7f3a91c2' });
```

Any MCP client can now list and call that tab's tools, and the list changes as the person navigates.

```text
browser tab  ──websocket──▶  axag-bridge  ──MCP (stdio)──▶  agent
```

### Why a relay rather than a server in the page

A tab has no address an agent can dial, and isn't running when the agent starts. So the tab connects **out** to a small local process, and that process is the MCP server the agent talks to.

Calls run **in the tab**, in the session the person is already signed into. No credentials pass through the relay, and the page's [safety enforcers](/docs/frameworks/safety) wrap every call — a bridged agent meets the same confirmation and tenant checks as one running inside the browser.

### What keeps it closed

- **Loopback only** — the relay binds `127.0.0.1`.
- **A pairing code** printed in the terminal and copied into the page.
- **An origin allowlist** via `--origin`, repeatable.
- **One tab at a time** — a second connection is refused, not silently promoted.
- **Calls expire** rather than hanging the agent when a tab stops answering.

### Configuring an MCP client

```json title="MCP server configuration"
{
  "mcpServers": {
    "axag-bridge": { "command": "npx", "args": ["axag-bridge", "--origin", "https://app.example.com"] }
  }
}
```

## Which to use

| Situation | Reach for |
|-----------|-----------|
| Browser ships WebMCP | Nothing extra — [`@axag/webmcp`](/docs/frameworks/runtime) uses it |
| Browser has no WebMCP, agent runs in the page | `@axag/shim` |
| Agent runs outside the browser (desktop client, terminal) | `@axag/shim` + `@axag/bridge` |

MCP is an open protocol, and its remote transport is Streamable HTTP; the standalone SSE transport is deprecated. The bridge speaks stdio by default because that is what desktop clients configure most easily.


# Authoring Guide

## Annotating Buttons and Action Controls

Source: https://axag.org/docs/authoring-guide/annotating-buttons

Buttons are the most common interactive elements requiring AXAG annotations. Every button that triggers an operation SHOULD carry semantic annotations.

## Basic Button Annotation
```html title="Read operation button"
<button
  <!-- axag-highlight-start -->
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  <!-- axag-highlight-end -->
  axag-required-parameters='["query"]'
  axag-scope="public"
  axag-risk-level="none"
  axag-description="Search the product catalog"
>
  Search
</button>
```

## Destructive Button
```html title="High-risk destructive action"
<button
  axag-intent="order.cancel"
  axag-entity="order"
  axag-action-type="write"
  axag-required-parameters='["order_id"]'
  axag-scope="user"
  <!-- axag-highlight-start -->
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-confirmation-message="This will cancel the order. Refund may take 3-5 business days."
  axag-side-effects='["refund_initiated","inventory_released"]'
  <!-- axag-highlight-end -->
>
  Cancel Order
</button>
```

## Icon Buttons
Icon buttons without text labels are especially important to annotate, as agents cannot infer intent from icons:
```html title="Icon-only button — annotation is critical"
<button
  aria-label="Delete item"
  <!-- axag-highlight-start -->
  axag-intent="cart.remove_item"
  axag-entity="cart_item"
  axag-action-type="delete"
  <!-- axag-highlight-end -->
  axag-required-parameters='["item_id"]'
  axag-risk-level="low"
>
  🗑️
</button>
```

## Toggle Buttons
```html title="Idempotent toggle"
<button
  axag-intent="notification.toggle"
  axag-entity="notification_preference"
  axag-action-type="write"
  axag-required-parameters='["notification_type","enabled"]'
  axag-scope="user"
  axag-risk-level="low"
  axag-idempotent="true"
>
  Enable Notifications
</button>
```

## Common Mistakes
- Annotating decorative buttons that don't trigger operations
- Using `axag-action-type="write"` for buttons that only navigate
- Forgetting to annotate icon-only buttons
- Not declaring side effects on buttons that trigger background processes

## Annotating Links and Navigation

Source: https://axag.org/docs/authoring-guide/annotating-links

Links that perform navigation SHOULD be annotated with `axag-action-type="navigate"`.

```html title="Navigation link — view product"
<a
  href="/products/123"
  axag-intent="product.view"
  axag-entity="product"
  axag-action-type="navigate"
  axag-required-parameters='["product_id"]'
  axag-scope="public"
  axag-risk-level="none"
>
  View Product Details
</a>
```

Links that trigger operations (e.g., "Download Report") should use the appropriate action type:
```html title="Action link — download report"
<a
  href="/api/reports/123/download"
  axag-intent="report.download"
  axag-entity="report"
  axag-action-type="read"
  axag-required-parameters='["report_id"]'
  axag-scope="user"
  axag-risk-level="none"
>
  Download Report
</a>
```

## Annotating Forms

Source: https://axag.org/docs/authoring-guide/annotating-forms

Annotate the form once. Its parameters come from the controls it already has: names, `required`, input types, constraints and labels. You only add AXAG attributes for what the markup can't say.

## A form with no parameter attributes

```html title="Lead creation form" showLineNumbers
<form axag="write:lead.create!low?idempotent=false&scope=tenant" axag-description="Create a new sales lead">
  <label for="first-name">First name</label>
  <input id="first-name" name="first_name" required maxlength="80">
  <label for="last-name">Last name</label>
  <input id="last-name" name="last_name" required maxlength="80">
  <label for="email">Work email</label>
  <input id="email" name="email" type="email" required>
  <label for="source">Lead source</label>
  <select id="source" name="source">
    <option value="web">Web</option>
    <option value="referral">Referral</option>
    <option value="event">Event</option>
  </select>
  <button type="submit">Create lead</button>
</form>
```

Generated manifest action:

```json title="axag-manifest.json — lead.create"
{
  "intent": "lead.create",
  "entity": "lead",
  "action_type": "write",
  "operation_id": "lead_create",
  "description": "Create a new sales lead",
  "required_parameters": [
    { "name": "first_name", "type": "string", "maxLength": 80, "description": "First name", "source": "harvested:html" },
    { "name": "last_name", "type": "string", "maxLength": 80, "description": "Last name", "source": "harvested:html" },
    { "name": "email", "type": "string", "format": "email", "description": "Work email", "source": "harvested:html" }
  ],
  "optional_parameters": [
    { "name": "source", "type": "string", "enum": ["web", "referral", "event"], "description": "Lead source", "source": "harvested:html" }
  ],
  "risk_level": "low",
  "idempotent": false,
  "scope": "tenant"
}
```

See [Schema Harvesting](/docs/semantic-manifest/schema-harvesting) for the full mapping from HTML to parameters.

## Where to put the annotation

- **On the `<form>`** — the usual choice.
- **On the submit button** — a `<button type="submit">` or `<input type="submit">` uses the form it belongs to, including through `form="form-id"`.
- **On anything else** — point it at the form with `axag-params-from="#form-id"`.

## Adding what the markup can't say

Use `axag-parameter-*` on a control to override what was harvested, or give a control without a `name` a parameter name:

```html title="Overrides on a control"
<input name="annual_revenue" inputmode="numeric"
  axag-parameter-type="number"
  axag-parameter-min="0"
  axag-parameter-description="Estimated annual revenue in USD">
```

If a backend schema already defines the parameters, bind it instead of repeating them. See [Bind Zod or OpenAPI Schemas](/docs/tutorials/bind-schemas).

## Key Rules
- Every control that is submitted SHOULD have a `name` (or `axag-parameter`); controls without one are reported as **AXAG-LINT-029**.
- Every control SHOULD have a `<label>`, `aria-label` or `aria-labelledby`; a placeholder is not a label (**AXAG-LINT-032**). The label becomes the parameter description agents read.
- Name radio and checkbox groups with a `<fieldset>` and `<legend>`, or `role="radiogroup"` with a label.
- Parameters declared on the annotation (`axag-required-parameters` or `req=`/`opt=` in the macro) take precedence over harvested ones, so use them only when the form doesn't reflect the real contract.
- Hidden, disabled and file inputs are not harvested.

## Annotating Tables and Bulk Actions

Source: https://axag.org/docs/authoring-guide/annotating-tables

Tables with row-level and bulk actions require annotations on action controls within table contexts.

## Row Action
```html title="Row-level actions — view & cancel" showLineNumbers
<table axag-entity="order" axag-scope="user">
  <tr>
    <td>Order #1234</td>
    <td>
      <button axag-intent="order.view" axag-action-type="navigate" axag-required-parameters='["order_id"]'>View</button>
      <button axag-intent="order.cancel" axag-action-type="write" axag-risk-level="high"
        axag-confirmation-required="true" axag-required-parameters='["order_id"]'>Cancel</button>
    </td>
  </tr>
</table>
```

## Bulk Action
```html title="Bulk action — export selected"
<button
  axag-intent="order.bulk_export"
  axag-entity="order"
  axag-action-type="read"
  axag-required-parameters='["order_ids"]'
  axag-scope="user"
  axag-risk-level="none"
  axag-description="Export selected orders as CSV"
>Export Selected</button>
```

## Annotating Search and Filters

Source: https://axag.org/docs/authoring-guide/annotating-search-filters

Search and filter controls combine read operations with multiple optional parameters.

```html title="Search with filters — form-level annotation" showLineNumbers
<div axag-intent="product.search" axag-entity="product" axag-action-type="read" axag-scope="public">
  <input axag-parameter="query" axag-parameter-type="string" axag-parameter-required="true" />
  <select axag-parameter="category" axag-parameter-type="enum" axag-parameter-required="false"
    axag-parameter-enum='["electronics","clothing","home"]'>
    <option value="">All Categories</option>
  </select>
  <input axag-parameter="price_min" axag-parameter-type="number" axag-parameter-min="0" />
  <input axag-parameter="price_max" axag-parameter-type="number" axag-parameter-min="0" />
  <button axag-risk-level="none" axag-idempotent="true">Search</button>
</div>
```

## Annotating Multi-Step Workflows

Source: https://axag.org/docs/authoring-guide/annotating-multi-step-workflows

Multi-step workflows use workflow attributes to declare step position and flow.

```html title="4-step checkout workflow" showLineNumbers
<div axag-workflow-id="checkout" axag-workflow-total-steps="4">
  <section axag-workflow-step="1" axag-workflow-next="checkout.select_shipping">
    <button axag-intent="checkout.review_cart" axag-entity="cart" axag-action-type="read">Review Cart</button>
  </section>
  <section axag-workflow-step="2" axag-workflow-next="checkout.enter_payment"
    axag-workflow-previous="checkout.review_cart">
    <button axag-intent="checkout.select_shipping" axag-entity="shipping" axag-action-type="write"
      axag-required-parameters='["shipping_method"]'>Select Shipping</button>
  </section>
  <section axag-workflow-step="3" axag-workflow-next="checkout.confirm"
    axag-workflow-previous="checkout.select_shipping">
    <button axag-intent="checkout.enter_payment" axag-entity="payment" axag-action-type="write"
      axag-required-parameters='["payment_method_id"]' axag-risk-level="high">Enter Payment</button>
  </section>
  <section axag-workflow-step="4" axag-workflow-previous="checkout.enter_payment">
    <button axag-intent="checkout.confirm" axag-entity="order" axag-action-type="write"
      axag-risk-level="high" axag-confirmation-required="true">Place Order</button>
  </section>
</div>
```

## Annotating Approval Gates

Source: https://axag.org/docs/authoring-guide/annotating-approval-gates

Operations requiring multi-party approval need explicit approval annotations.

```html title="Approval gate — refund processing" showLineNumbers
<button
  axag-intent="refund.process"
  axag-entity="refund"
  axag-action-type="write"
  axag-required-parameters='["order_id","amount","reason"]'
  axag-risk-level="high"
  axag-approval-required="true"
  axag-approval-roles='["finance_manager"]'
  axag-approval-count="1"
  axag-scope="tenant"
>Process Refund</button>
```

The agent runtime will submit an approval request rather than executing directly, then wait for the required number of approvals from authorized roles.

## Annotating Destructive Actions

Source: https://axag.org/docs/authoring-guide/annotating-destructive-actions

Destructive actions (delete, purge, revoke) require explicit safety annotations.

```html title="🔴 Critical destructive action — account deletion" showLineNumbers
<button
  axag-intent="account.delete"
  axag-entity="account"
  axag-action-type="delete"
  axag-required-parameters='["account_id","confirmation_code"]'
  axag-risk-level="critical"
  axag-confirmation-required="true"
  axag-confirmation-message="This will permanently delete the account and all data. This cannot be undone."
  axag-idempotent="false"
  axag-side-effects='["data_purged","subscriptions_cancelled","api_keys_revoked"]'
  axag-scope="user"
>Delete Account</button>
```

Rules:
- `delete` actions MUST declare `axag-risk-level` of `medium` or higher
- `critical` risk actions MUST have `axag-confirmation-required="true"`
- Irreversible actions SHOULD declare `axag-idempotent="false"`
- All side effects MUST be declared

## Annotating Async Operations

Source: https://axag.org/docs/authoring-guide/annotating-async-operations

Asynchronous operations produce results after a delay. Annotate them with postconditions and polling hints.

```html title="Async operation — report generation" showLineNumbers
<button
  axag-intent="report.generate"
  axag-entity="report"
  axag-action-type="write"
  axag-required-parameters='["report_type","date_range"]'
  axag-risk-level="none"
  axag-async="true"
  axag-async-polling-endpoint="/api/reports/{report_id}/status"
  axag-async-estimated-duration="30s"
  axag-postconditions='["report_ready"]'
>Generate Report</button>
```

The agent runtime should poll the status endpoint rather than blocking on the initial invocation.

## Annotating Composite Flows

Source: https://axag.org/docs/authoring-guide/annotating-composite-flows

Composite flows combine multiple operations into a logical workflow. Each step is annotated individually with workflow attributes linking them.

Use `axag-workflow-id` to group steps and `axag-workflow-step` to declare order. Preconditions and postconditions chain steps automatically.

## Annotating Embedded Widgets

Source: https://axag.org/docs/authoring-guide/annotating-embedded-widgets

Third-party widgets (payment forms, maps, calendars) embedded in your application should be annotated at the container level.

```html title="Third-party widget — Stripe payment" showLineNumbers
<div
  axag-intent="payment.collect"
  axag-entity="payment"
  axag-action-type="write"
  axag-required-parameters='["amount","currency","payment_method"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-scope="user"
  axag-widget-type="third-party"
  axag-widget-provider="stripe"
>
  <!-- Stripe Elements iframe renders here -->
</div>
```

The container annotation describes the semantic operation even though the internal widget implementation is opaque.

## Annotation Reuse Through Component Libraries

Source: https://axag.org/docs/authoring-guide/annotation-reuse

In React, Vue, and other component-based frameworks, create annotated wrapper components for reuse.

## React Example (TypeScript)
```tsx title="AXAGButton.tsx — reusable annotated component" showLineNumbers
interface AXAGButtonProps {
  intent: string;
  entity: string;
  actionType: 'read' | 'write' | 'delete' | 'navigate';
  requiredParameters?: string[];
  riskLevel?: 'none' | 'low' | 'medium' | 'high' | 'critical';
  scope?: string;
  description?: string;
  confirmationRequired?: boolean;
  children: React.ReactNode;
  onClick?: () => void;
}

  intent, entity, actionType, requiredParameters = [],
  riskLevel = 'none', scope, description,
  confirmationRequired = false, children, onClick,
}: AXAGButtonProps) {
  return (
    <button
      axag-intent={intent}
      axag-entity={entity}
      axag-action-type={actionType}
      axag-required-parameters={JSON.stringify(requiredParameters)}
      axag-risk-level={riskLevel}
      axag-scope={scope}
      axag-description={description}
      axag-confirmation-required={String(confirmationRequired)}
      onClick={onClick}
    >
      {children}
    </button>
  );
}
```

## Usage
```tsx title="Usage — consistent annotations everywhere"

  Search

```

This pattern ensures consistency across the application and reduces annotation duplication.


# Use Cases

## Use Cases Overview

Source: https://axag.org/docs/use-cases/overview

AXAG is domain-agnostic. This section demonstrates how AXAG applies across industries where automated interaction and scraping are currently common.

## Cross-Domain Architecture

```mermaid
graph TD
    EC["🛒 E-Commerce"] --> AXAG["AXAG Semantic Contract"]
    MK["📣 Marketing"] --> AXAG
    CRM["📊 CRM/Sales"] --> AXAG
    TV["✈️ Travel"] --> AXAG
    AN["📈 Analytics"] --> AXAG
    SP["🎧 Support"] --> AXAG
    JB["💼 Job Platforms"] --> AXAG

    AXAG --> SM["Semantic Manifest"]
    SM --> TR["Tool Registry"]
    TR --> AR["Agent Runtime"]
```

Each domain exposes its operations through the same semantic contract format. Agents interact with semantic operations rather than scraping domain-specific interface structures.

## Domain Coverage

| Domain | Key Operations | Common Scraping Target |
|--------|---------------|----------------------|
| **E-Commerce** | Search, cart, checkout, tracking, returns | Product cards, price elements, cart widgets |
| **Marketing** | Campaigns, audiences, experiments, scheduling | Dashboard layouts, form wizards |
| **Sales/CRM** | Leads, opportunities, pipeline, forecasting | Data tables, stage dropdowns |
| **Travel** | Flights, hotels, booking, cancellation | Search results, availability grids |
| **Jobs** | Search, applications, interviews | Job listings, application forms |
| **Analytics** | Reports, dashboards, exports | Chart data, filter panels |
| **Support** | Tickets, escalation, knowledge base | Ticket queues, status dropdowns |
| **Enterprise SaaS** | CRUD, admin, tenant operations | Settings panels, user management |

## Cross-Domain Scraping Replacement Comparison

| Domain | Current Scraping Method | Common Failure Mode | AXAG Semantic Intent | Generated Tool |
|--------|------------------------|--------------------|--------------------|---------------|
| E-Commerce | Parse product card DOM | CSS class churn | `product.search` | `product_search` |
| Marketing | Scrape campaign dashboard | Dynamic rendering | `campaign.create` | `campaign_create` |
| CRM | Extract pipeline table | Layout restructuring | `opportunity.update_stage` | `opportunity_update_stage` |
| Travel | Parse search results grid | Anti-bot defenses | `flight.search` | `flight_search` |
| Jobs | Scrape job listing cards | Localization changes | `job.search` | `job_search` |
| Analytics | Extract chart data | Async loading | `report.generate` | `report_generate` |
| Support | Parse ticket queue | Modal complexity | `ticket.create` | `ticket_create` |

## Next Steps

Explore domain-specific use cases:
- [E-Commerce](/docs/use-cases/ecommerce/product-search)
- [Marketing](/docs/use-cases/marketing/campaign-creation)
- [Sales & CRM](/docs/use-cases/crm/lead-creation)
- [Travel & Booking](/docs/use-cases/travel/search-and-reservation)
- [Job Platforms](/docs/use-cases/jobs/job-search)
- [Analytics & BI](/docs/use-cases/analytics/dashboard-filtering)
- [Customer Support](/docs/use-cases/support/ticket-creation)
- [Enterprise & SaaS](/docs/use-cases/enterprise/crud-dashboard)


# E-Commerce

## E-Commerce: Product Search

Source: https://axag.org/docs/use-cases/ecommerce/product-search

## Problem Statement
Product search is the most common e-commerce interaction. Agents need to search product catalogs with structured queries, but current approaches require scraping search result DOM, parsing product cards, and extracting prices from formatted strings.

## Why Human-Only Semantics Fail
- Search inputs don't declare what entity they search
- Filter controls (price sliders, category dropdowns) don't declare parameter types or ranges
- Results are rendered as visual cards with no structured output contract
- Pagination controls don't declare total results or page boundaries

## Why Scraping Fails Here
- Product card HTML changes with every design iteration
- CSS class names are hashed by build tools
- Price formatting varies by locale ($19.99, €19,99, ¥1999)
- A/B tests alter result layout and card structure
- Lazy loading and infinite scroll make DOM parsing unreliable

## How AXAG Eliminates Scraping
Agents read the AXAG annotation and Semantic Manifest to discover `product.search` as a typed operation with declared parameters, then invoke the generated MCP tool directly.

## Annotated UI Example
```html title="Search button with AXAG annotations"
<button
  <!-- axag-highlight-start -->
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  <!-- axag-highlight-end -->
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category","price_min","price_max","brand","sort_by","page","page_size"]'
  axag-scope="public"
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Search the product catalog with text query and optional filters"
>Search Products</button>
```

## Semantic Manifest Excerpt
```json title="axag-manifest.json — product.search" showLineNumbers
{
  "intent": "product.search",
  "entity": "product",
  "action_type": "read",
  "operation_id": "product_search",
  "description": "Search the product catalog with text query and optional filters",
  "required_parameters": [{ "name": "query", "type": "string" }],
  "optional_parameters": [
    { "name": "category", "type": "string" },
    { "name": "price_min", "type": "number", "min": 0 },
    { "name": "price_max", "type": "number", "min": 0 },
    { "name": "brand", "type": "string" },
    {
      "name": "sort_by",
      "type": "string",
      "enum": ["relevance", "price_asc", "price_desc", "newest", "rating"]
    },
    { "name": "page", "type": "number", "min": 1 },
    { "name": "page_size", "type": "number", "min": 1, "max": 100 }
  ],
  "risk_level": "none",
  "idempotent": true,
  "scope": "public"
}
```

## Generated Tool Example
```json title="tools/product_search.json" showLineNumbers
{
  "name": "product_search",
  "description": "Search the product catalog with text query and optional filters",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "category": { "type": "string" },
      "price_min": { "type": "number", "minimum": 0 },
      "price_max": { "type": "number", "minimum": 0 },
      "sort_by": {
        "type": "string",
        "enum": ["relevance", "price_asc", "price_desc", "newest", "rating"]
      }
    },
    "required": ["query"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "product.search",
    "source_entity": "product"
  }
}
```

## Testing Checklist
- [ ] Search with query-only returns results
- [ ] Search with filters narrows results correctly
- [ ] Empty query returns validation error
- [ ] Pagination works with page/page_size parameters
- [ ] Sort options produce correct ordering

## E-Commerce: Cart & Checkout

Source: https://axag.org/docs/use-cases/ecommerce/cart-and-checkout

## Problem Statement
Adding items to a cart and beginning checkout are high-intent, multi-step flows. Agents must be able to add items (write), view the cart (read), update quantities (write), remove items (write), and initiate checkout (write with side-effects).

## Why Human-Only Semantics Fail
- "Add to Cart" buttons don't declare which product ID, variant, or quantity they affect
- Checkout flows are multi-step wizards with no declared state machine
- Shipping/payment forms don't expose their parameter schemas to machines
- "Place Order" has financial side-effects that no DOM attribute communicates

## Why Scraping Fails Here
- Cart state is stored in cookies/session, not in the DOM
- Quantity controls use custom components with inconsistent selectors
- Checkout steps load dynamically via SPA navigation
- Payment forms are in iframes from third-party providers
- Anti-bot protections specifically target checkout scrapers

## How AXAG Eliminates Scraping
AXAG annotates each cart and checkout operation with intent, parameters, preconditions, and risk level. The generated tools are safe, typed, and declare side-effects explicitly.

## Annotated UI Example
```html title="Cart & Checkout actions" showLineNumbers
<!-- Add to Cart -->
<button
  <!-- axag-highlight-start -->
  axag-intent="cart.add_item"
  axag-entity="cart"
  axag-action-type="write"
  <!-- axag-highlight-end -->
  axag-required-parameters='["product_id","quantity"]'
  axag-optional-parameters='["variant_id"]'
  axag-preconditions='["product must be in stock"]'
  axag-postconditions='["cart updated with new item"]'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-description="Add a product to the shopping cart"
>Add to Cart</button>

<!-- Begin Checkout -->
<button
  <!-- axag-highlight-start -->
  axag-intent="cart.begin_checkout"
  axag-entity="cart"
  axag-action-type="write"
  <!-- axag-highlight-end -->
  axag-required-parameters='["cart_id"]'
  axag-optional-parameters='["shipping_method","promo_code"]'
  axag-preconditions='["cart must have at least one item","user must be authenticated"]'
  axag-postconditions='["checkout session created","inventory reserved for 15 minutes"]'
  <!-- axag-highlight-start -->
  axag-risk-level="medium"
  axag-confirmation-required="true"
  <!-- axag-highlight-end -->
  axag-idempotent="false"
  axag-side-effects='["inventory_reservation","price_lock"]'
  axag-description="Begin the checkout process for the current cart"
>Proceed to Checkout</button>
```

## Semantic Manifest Excerpt
```json title="axag-manifest.json — cart actions" showLineNumbers
{
  "actions": [
    {
      "intent": "cart.add_item",
      "entity": "cart",
      "action_type": "write",
      "operation_id": "cart_add_item",
      "description": "Add a product to the shopping cart",
      "required_parameters": [
        { "name": "product_id", "type": "string" },
        { "name": "quantity", "type": "integer", "min": 1, "max": 99 }
      ],
      "optional_parameters": [{ "name": "variant_id", "type": "string" }],
      "risk_level": "low",
      "idempotent": false,
      "preconditions": ["product must be in stock"],
      "postconditions": ["cart updated with new item"]
    },
    {
      "intent": "cart.begin_checkout",
      "entity": "cart",
      "action_type": "write",
      "operation_id": "cart_begin_checkout",
      "description": "Begin the checkout process for the current cart",
      "required_parameters": [{ "name": "cart_id", "type": "string" }],
      "optional_parameters": [
        { "name": "shipping_method", "type": "string" },
        { "name": "promo_code", "type": "string" }
      ],
      "risk_level": "medium",
      "confirmation_required": true,
      "idempotent": false,
      "side_effects": ["inventory_reservation", "price_lock"],
      "preconditions": ["cart must have at least one item", "user must be authenticated"],
      "postconditions": ["checkout session created", "inventory reserved for 15 minutes"]
    }
  ]
}
```

## Generated Tool Examples
```json
{
  "name": "cart_add_item",
  "description": "Add a product to the shopping cart",
  "input_schema": {
    "type": "object",
    "properties": {
      "product_id": { "type": "string" },
      "quantity": { "type": "integer", "minimum": 1, "maximum": 99 },
      "variant_id": { "type": "string" }
    },
    "required": ["product_id", "quantity"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "low",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "preconditions": ["product must be in stock"],
    "source_intent": "cart.add_item",
    "source_entity": "cart"
  }
}
```

## Constraints & Safety Notes
- `cart.begin_checkout` requires confirmation because it reserves inventory
- Quantity is bounded to 1–99 to prevent abuse
- Cart operations are NOT idempotent — adding twice doubles the quantity
- `cart_begin_checkout` side-effects (inventory reservation, price lock) are time-bounded (15 min)

## E-Commerce: Order Tracking

Source: https://axag.org/docs/use-cases/ecommerce/order-tracking

## Problem Statement
After purchase, users need to track order status, estimated delivery, and shipment details. Agents must query order status without side-effects.

## Why Human-Only Semantics Fail
- Order status is displayed with icons and visual timelines, not structured data
- "Track Order" links open external carrier pages with different DOM structures
- Status labels ("Shipped", "In Transit", "Out for Delivery") are not standardized

## Why Scraping Fails Here
- External carrier tracking pages have completely different HTML
- Order pages require authentication cookies
- Status timeline components use canvas/SVG rendering
- Real-time updates via WebSocket don't reflect in static DOM

## How AXAG Eliminates Scraping
`order.track` is a read-only operation with a declared schema. Agents call the generated tool and receive structured status data.

## Annotated UI Example
```html
<button
  axag-intent="order.track"
  axag-entity="order"
  axag-action-type="read"
  axag-required-parameters='["order_id"]'
  axag-scope="user"
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Get the current status and tracking details for an order"
>Track Order</button>
```

## Semantic Manifest Excerpt
```json
{
  "intent": "order.track",
  "entity": "order",
  "action_type": "read",
  "operation_id": "order_track",
  "description": "Get the current status and tracking details for an order",
  "required_parameters": [{ "name": "order_id", "type": "string" }],
  "optional_parameters": [],
  "risk_level": "none",
  "idempotent": true,
  "scope": "user"
}
```

## Generated Tool Example
```json
{
  "name": "order_track",
  "description": "Get the current status and tracking details for an order",
  "input_schema": {
    "type": "object",
    "properties": { "order_id": { "type": "string" } },
    "required": ["order_id"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "order.track",
    "source_entity": "order"
  }
}
```

## Constraints & Safety Notes
- Read-only, no side-effects
- Scoped to `user` — agents can only track orders belonging to the authenticated user
- No tenant-crossing: User A cannot track User B's order

## E-Commerce: Returns & Refunds

Source: https://axag.org/docs/use-cases/ecommerce/returns

## Problem Statement
Initiating a return involves selecting an order, choosing items, specifying a reason, and optionally uploading evidence. This is a destructive operation with financial side-effects (refund processing).

## Why Human-Only Semantics Fail
- Return forms are multi-step wizards with no declared state machine
- Reason dropdowns don't expose their enum values
- Return eligibility (within 30 days, unused, etc.) is visually indicated but not machine-readable
- Refund amount calculation is displayed but its formula is opaque

## Why Scraping Fails Here
- Multi-step return forms use SPA navigation
- Eligibility checks happen server-side; DOM only shows the result
- File upload components use custom dropzones
- Confirmation modals are dynamically rendered

## How AXAG Eliminates Scraping
`return.initiate` is annotated with preconditions (eligibility), required parameters (reason, items), risk level, and confirmation requirements. The agent can validate eligibility before attempting the action.

## Annotated UI Example
```html
<button
  axag-intent="return.initiate"
  axag-entity="return"
  axag-action-type="write"
  axag-required-parameters='["order_id","items","reason"]'
  axag-optional-parameters='["notes","evidence_urls"]'
  axag-preconditions='["order must be within return window","items must not be final-sale"]'
  axag-postconditions='["return request created","refund processing initiated"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-side-effects='["refund_processing","inventory_update"]'
  axag-description="Initiate a return for one or more items from an order"
>Start Return</button>
```

## Semantic Manifest Excerpt
```json
{
  "intent": "return.initiate",
  "entity": "return",
  "action_type": "write",
  "operation_id": "return_initiate",
  "description": "Initiate a return for one or more items from an order",
  "required_parameters": [
    { "name": "order_id", "type": "string" },
    {
      "name": "items",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item_id": { "type": "string" },
          "quantity": { "type": "integer", "minimum": 1 }
        }
      }
    },
    {
      "name": "reason",
      "type": "string",
      "enum": ["defective", "wrong_item", "not_as_described", "changed_mind", "other"]
    }
  ],
  "optional_parameters": [
    { "name": "notes", "type": "string", "maxLength": 1000 },
    { "name": "evidence_urls", "type": "array", "items": { "type": "string" } }
  ],
  "risk_level": "high",
  "confirmation_required": true,
  "idempotent": false,
  "side_effects": ["refund_processing", "inventory_update"],
  "preconditions": ["order must be within return window", "items must not be final-sale"],
  "postconditions": ["return request created", "refund processing initiated"]
}
```

## Generated Tool Example
```json
{
  "name": "return_initiate",
  "description": "Initiate a return for one or more items from an order",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string" },
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "item_id": { "type": "string" },
            "quantity": { "type": "integer", "minimum": 1 }
          },
          "required": ["item_id", "quantity"]
        }
      },
      "reason": {
        "type": "string",
        "enum": ["defective", "wrong_item", "not_as_described", "changed_mind", "other"]
      },
      "notes": { "type": "string", "maxLength": 1000 }
    },
    "required": ["order_id", "items", "reason"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "high",
    "idempotent": false,
    "confirmation_required": true,
    "approval_required": false,
    "side_effects": ["refund_processing", "inventory_update"],
    "preconditions": ["order must be within return window", "items must not be final-sale"],
    "source_intent": "return.initiate",
    "source_entity": "return"
  }
}
```

## Constraints & Safety Notes
- **High risk**: triggers financial refund processing
- **Confirmation required**: agent MUST confirm with user before executing
- **Not idempotent**: submitting twice creates duplicate return requests
- Preconditions are machine-checkable: return window and final-sale status
- Reason enum ensures valid categorization


# Marketing Automation

## Marketing: Campaign Creation

Source: https://axag.org/docs/use-cases/marketing/campaign-creation

## Problem Statement
Creating a marketing campaign involves naming the campaign, selecting channels, defining audience segments, setting budgets, and configuring creative assets. This is a multi-field write operation with complex parameter schemas.

## Why Human-Only Semantics Fail
- Campaign creation forms span multiple tabs/steps
- Channel selection uses custom chip components
- Budget inputs don't declare currency or constraints
- Audience segment pickers are complex filter builders with no schema

## Why Scraping Fails Here
- Multi-tab forms don't exist as a single DOM snapshot
- Rich text editors for creative content use contenteditable or iframes
- Audience builder components are deeply nested interactive trees
- Draft save and publish are distinct actions but look like similar buttons

## How AXAG Eliminates Scraping
`campaign.create` declares the full parameter schema including nested objects for budget and audience. Agents construct a valid request without navigating form UIs.

## Annotated UI Example
```html title="Marketing — create campaign"
<button
  axag-intent="campaign.create"
  axag-entity="campaign"
  axag-action-type="write"
  axag-required-parameters='["name","channel","audience_segment_id","budget"]'
  axag-optional-parameters='["start_date","end_date","creative_asset_ids","tags"]'
  axag-preconditions='["user must have campaign_create permission"]'
  axag-postconditions='["campaign created in draft status"]'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-description="Create a new marketing campaign"
>Create Campaign</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — campaign.create" showLineNumbers
{
  "intent": "campaign.create",
  "entity": "campaign",
  "action_type": "write",
  "operation_id": "campaign_create",
  "description": "Create a new marketing campaign",
  "required_parameters": [
    { "name": "name", "type": "string", "maxLength": 200 },
    { "name": "channel", "type": "string", "enum": ["email", "sms", "push", "social", "display"] },
    { "name": "audience_segment_id", "type": "string" },
    {
      "name": "budget",
      "type": "object",
      "properties": {
        "amount": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] }
      }
    }
  ],
  "optional_parameters": [
    { "name": "start_date", "type": "string", "format": "date" },
    { "name": "end_date", "type": "string", "format": "date" },
    { "name": "creative_asset_ids", "type": "array", "items": { "type": "string" } },
    { "name": "tags", "type": "array", "items": { "type": "string" } }
  ],
  "risk_level": "low",
  "idempotent": false,
  "preconditions": ["user must have campaign_create permission"],
  "postconditions": ["campaign created in draft status"]
}
```

## Generated Tool Example
```json title="Tool — campaign_create"
{
  "name": "campaign_create",
  "description": "Create a new marketing campaign",
  "input_schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "maxLength": 200 },
      "channel": { "type": "string", "enum": ["email", "sms", "push", "social", "display"] },
      "audience_segment_id": { "type": "string" },
      "budget": {
        "type": "object",
        "properties": {
          "amount": { "type": "number", "minimum": 0 },
          "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] }
        },
        "required": ["amount", "currency"]
      },
      "start_date": { "type": "string", "format": "date" },
      "end_date": { "type": "string", "format": "date" }
    },
    "required": ["name", "channel", "audience_segment_id", "budget"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "low",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "campaign.create",
    "source_entity": "campaign"
  }
}
```

## Constraints & Safety Notes
- Creates in **draft** status — not yet live
- Budget amount has minimum 0 constraint to prevent negative values
- Requires `campaign_create` permission
- Not idempotent — calling twice creates two campaigns

## Marketing: Audience Segmentation

Source: https://axag.org/docs/use-cases/marketing/audience-segmentation

## Problem Statement
Building audience segments involves composing filter rules (demographics, behavior, purchase history) into reusable groups. This is a complex query-builder interaction.

## Why Human-Only Semantics Fail
- Filter builders use drag-and-drop with nested AND/OR logic
- Condition types vary per field (equals, contains, greater-than, between)
- Segment preview counts are calculated server-side
- The composition model (union, intersection, exclusion) is purely visual

## Why Scraping Fails Here
- Query builders render as dynamic nested trees
- Each filter row is a separate component instance
- Drag-and-drop reordering doesn't change the DOM in a parseable way
- Preview data requires API calls that scrapers can't trigger

## How AXAG Eliminates Scraping
`audience.create_segment` declares a structured filter schema that agents compose programmatically. No visual interaction required.

## Annotated UI Example
```html title="Marketing — create audience segment"
<button
  axag-intent="audience.create_segment"
  axag-entity="audience_segment"
  axag-action-type="write"
  axag-required-parameters='["name","rules"]'
  axag-optional-parameters='["description","tags"]'
  axag-risk-level="none"
  axag-idempotent="false"
  axag-description="Create a reusable audience segment with filter rules"
>Save Segment</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — audience.create_segment" showLineNumbers
{
  "intent": "audience.create_segment",
  "entity": "audience_segment",
  "action_type": "write",
  "operation_id": "audience_create_segment",
  "description": "Create a reusable audience segment with filter rules",
  "required_parameters": [
    { "name": "name", "type": "string", "maxLength": 100 },
    {
      "name": "rules",
      "type": "object",
      "properties": {
        "operator": { "type": "string", "enum": ["AND", "OR"] },
        "conditions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "field": { "type": "string" },
              "operator": {
                "type": "string",
                "enum": ["equals", "not_equals", "contains", "gt", "lt", "between", "in"]
              },
              "value": {}
            }
          }
        }
      }
    }
  ],
  "optional_parameters": [
    { "name": "description", "type": "string" },
    { "name": "tags", "type": "array", "items": { "type": "string" } }
  ],
  "risk_level": "none",
  "idempotent": false
}
```

## Generated Tool Example
```json title="Tool — audience_create_segment"
{
  "name": "audience_create_segment",
  "description": "Create a reusable audience segment with filter rules",
  "input_schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "maxLength": 100 },
      "rules": {
        "type": "object",
        "properties": {
          "operator": { "type": "string", "enum": ["AND", "OR"] },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": { "type": "string" },
                "operator": {
                  "type": "string",
                  "enum": ["equals", "not_equals", "contains", "gt", "lt", "between", "in"]
                },
                "value": {}
              },
              "required": ["field", "operator", "value"]
            }
          }
        },
        "required": ["operator", "conditions"]
      }
    },
    "required": ["name", "rules"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "none",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "audience.create_segment",
    "source_entity": "audience_segment"
  }
}
```

## Constraints & Safety Notes
- No risk — segments are metadata, not user-affecting actions
- Rules use a composable AND/OR model with typed conditions
- Field names in conditions reference the data model (e.g., `age`, `purchase_count`, `last_active`)

## Marketing: Campaign Scheduling

Source: https://axag.org/docs/use-cases/marketing/campaign-scheduling

## Problem Statement
Scheduling a campaign to go live involves setting a date/time, timezone, and optionally configuring send-time optimization. This transitions a campaign from draft to scheduled — a state change with real-world consequences.

## Why Human-Only Semantics Fail
- Date/time pickers don't declare their timezone handling
- "Schedule" vs "Send Now" buttons don't declare the difference in side-effects
- Send-time optimization toggles don't declare what they enable
- The state transition (draft → scheduled) is implicit

## Why Scraping Fails Here
- Calendar/date pickers are complex widgets that differ across libraries
- Timezone dropdowns contain 400+ options rendered lazily
- Scheduling confirmation modals appear conditionally
- Time validation (can't schedule in the past) happens client-side

## How AXAG Eliminates Scraping
`campaign.schedule` declares the exact parameters (campaign_id, send_at, timezone), preconditions (must be in draft with approved creative), and side-effects (messages will be sent at the scheduled time).

## Annotated UI Example
```html title="Marketing — schedule campaign ⚠️" showLineNumbers
<button
  axag-intent="campaign.schedule"
  axag-entity="campaign"
  axag-action-type="write"
  axag-required-parameters='["campaign_id","send_at","timezone"]'
  axag-optional-parameters='["send_time_optimization"]'
  axag-preconditions='["campaign must be in draft status","creative must be approved"]'
  axag-postconditions='["campaign status changed to scheduled","messages queued for delivery"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["message_delivery_queued"]'
  axag-description="Schedule a campaign for delivery at a specific date and time"
>Schedule Campaign</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — campaign.schedule" showLineNumbers
{
  "intent": "campaign.schedule",
  "entity": "campaign",
  "action_type": "write",
  "operation_id": "campaign_schedule",
  "description": "Schedule a campaign for delivery at a specific date and time",
  "required_parameters": [
    { "name": "campaign_id", "type": "string" },
    { "name": "send_at", "type": "string", "format": "datetime" },
    { "name": "timezone", "type": "string" }
  ],
  "optional_parameters": [{ "name": "send_time_optimization", "type": "boolean", "default": false }],
  "risk_level": "high",
  "confirmation_required": true,
  "idempotent": true,
  "side_effects": ["message_delivery_queued"],
  "preconditions": ["campaign must be in draft status", "creative must be approved"],
  "postconditions": ["campaign status changed to scheduled", "messages queued for delivery"]
}
```

## Generated Tool Example
```json title="Tool — campaign_schedule"
{
  "name": "campaign_schedule",
  "description": "Schedule a campaign for delivery at a specific date and time",
  "input_schema": {
    "type": "object",
    "properties": {
      "campaign_id": { "type": "string" },
      "send_at": { "type": "string", "format": "date-time" },
      "timezone": { "type": "string" },
      "send_time_optimization": { "type": "boolean", "default": false }
    },
    "required": ["campaign_id", "send_at", "timezone"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "high",
    "idempotent": true,
    "confirmation_required": true,
    "approval_required": false,
    "side_effects": ["message_delivery_queued"],
    "source_intent": "campaign.schedule",
    "source_entity": "campaign"
  }
}
```

## Constraints & Safety Notes
- **High risk**: scheduling triggers message delivery to potentially millions of recipients
- **Confirmation required**: agent MUST get user approval
- **Idempotent**: re-scheduling with the same parameters is safe (updates the schedule)
- `send_at` must be in the future; past dates are rejected
- Preconditions ensure the campaign is review-ready before scheduling


# Sales & CRM

## CRM: Lead Creation

Source: https://axag.org/docs/use-cases/crm/lead-creation

## Problem Statement
Creating a lead in a CRM captures contact information, source, and initial qualification data. This is a standard write operation, but CRM forms often have dozens of optional fields, custom fields, and auto-population logic.

## Why Human-Only Semantics Fail
- CRM forms have 20+ fields with no declaration of which are required
- Custom fields are tenant-specific and not discoverable from the DOM
- Auto-population (company lookup from email domain) is invisible to scrapers
- Duplicate detection happens server-side; the form doesn't communicate it

## Why Scraping Fails Here
- CRM UIs vary massively between tenants (Salesforce, HubSpot, custom)
- Custom fields add dynamic form rows
- Inline validation messages are transient DOM elements
- OAuth-protected pages block unauthenticated scrapers

## How AXAG Eliminates Scraping
`lead.create` declares the full field schema, required/optional distinctions, and any duplicate-detection behavior. Agents submit structured data directly.

## Annotated UI Example
```html title="CRM — lead creation button" showLineNumbers
<button
  axag-intent="lead.create"
  axag-entity="lead"
  axag-action-type="write"
  axag-required-parameters='["first_name","last_name","email"]'
  axag-optional-parameters='["company","phone","source","notes","custom_fields"]'
  axag-postconditions='["lead created","assignment rules triggered"]'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-scope="tenant"
  axag-description="Create a new lead in the CRM"
>Create Lead</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — lead.create" showLineNumbers
{
  "intent": "lead.create",
  "entity": "lead",
  "action_type": "write",
  "operation_id": "lead_create",
  "description": "Create a new lead in the CRM",
  "required_parameters": [
    { "name": "first_name", "type": "string" },
    { "name": "last_name", "type": "string" },
    { "name": "email", "type": "string", "format": "email" }
  ],
  "optional_parameters": [
    { "name": "company", "type": "string" },
    { "name": "phone", "type": "string" },
    {
      "name": "source",
      "type": "string",
      "enum": ["website", "referral", "event", "cold_outreach", "partner", "other"]
    },
    { "name": "notes", "type": "string", "maxLength": 5000 },
    { "name": "custom_fields", "type": "object" }
  ],
  "risk_level": "low",
  "idempotent": false,
  "scope": "tenant",
  "postconditions": ["lead created", "assignment rules triggered"]
}
```

## Generated Tool Example
```json title="Tool — lead_create" showLineNumbers
{
  "name": "lead_create",
  "description": "Create a new lead in the CRM",
  "input_schema": {
    "type": "object",
    "properties": {
      "first_name": { "type": "string" },
      "last_name": { "type": "string" },
      "email": { "type": "string", "format": "email" },
      "company": { "type": "string" },
      "phone": { "type": "string" },
      "source": {
        "type": "string",
        "enum": ["website", "referral", "event", "cold_outreach", "partner", "other"]
      },
      "notes": { "type": "string", "maxLength": 5000 },
      "custom_fields": { "type": "object" }
    },
    "required": ["first_name", "last_name", "email"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "low",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "lead.create",
    "source_entity": "lead"
  }
}
```

## Constraints & Safety Notes
- **Not idempotent**: duplicate submissions create duplicate leads
- **Scoped to tenant**: agent cannot create leads in other tenants
- `custom_fields` is a flexible object for tenant-specific extensions
- Post-creation side-effect: assignment rules may auto-assign the lead to a sales rep

## CRM: Opportunity Progression

Source: https://axag.org/docs/use-cases/crm/opportunity-progression

## Problem Statement
Moving a sales opportunity through pipeline stages (Prospecting → Qualification → Proposal → Negotiation → Closed Won/Lost) is a state-machine operation that requires specific fields at each stage transition.

## Why Human-Only Semantics Fail
- Pipeline boards use drag-and-drop to move deals between columns
- Required fields per stage are enforced at submit time, not declared upfront
- Stage-specific forms appear conditionally
- Win probability and amount fields don't declare their constraints

## Why Scraping Fails Here
- Kanban boards use complex virtual scrolling
- Drag-and-drop events don't produce standard form submissions
- Stage validation errors appear as toast notifications
- The pipeline is a single-page application with no URL changes per stage

## How AXAG Eliminates Scraping
`opportunity.advance_stage` declares the valid stage transitions, required fields per stage, and any approval requirements for high-value deals.

## Annotated UI Example
```html title="CRM — advance opportunity stage" showLineNumbers
<button
  axag-intent="opportunity.advance_stage"
  axag-entity="opportunity"
  axag-action-type="write"
  axag-required-parameters='["opportunity_id","target_stage"]'
  axag-optional-parameters='["amount","close_date","win_probability","notes"]'
  axag-preconditions='["opportunity must be in a valid predecessor stage","required stage fields must be populated"]'
  axag-postconditions='["opportunity moved to target stage","stage history updated"]'
  axag-risk-level="medium"
  axag-idempotent="true"
  axag-scope="tenant"
  axag-description="Advance an opportunity to the next pipeline stage"
>Move to Next Stage</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — opportunity.advance_stage" showLineNumbers
{
  "intent": "opportunity.advance_stage",
  "entity": "opportunity",
  "action_type": "write",
  "operation_id": "opportunity_advance_stage",
  "description": "Advance an opportunity to the next pipeline stage",
  "required_parameters": [
    { "name": "opportunity_id", "type": "string" },
    {
      "name": "target_stage",
      "type": "string",
      "enum": [
        "prospecting",
        "qualification",
        "proposal",
        "negotiation",
        "closed_won",
        "closed_lost"
      ]
    }
  ],
  "optional_parameters": [
    { "name": "amount", "type": "number", "min": 0 },
    { "name": "close_date", "type": "string", "format": "date" },
    { "name": "win_probability", "type": "number", "min": 0, "max": 100 },
    { "name": "notes", "type": "string" }
  ],
  "risk_level": "medium",
  "idempotent": true,
  "scope": "tenant",
  "preconditions": [
    "opportunity must be in a valid predecessor stage",
    "required stage fields must be populated"
  ],
  "postconditions": ["opportunity moved to target stage", "stage history updated"]
}
```

## Generated Tool Example
```json title="Tool — opportunity_advance_stage"
{
  "name": "opportunity_advance_stage",
  "description": "Advance an opportunity to the next pipeline stage",
  "input_schema": {
    "type": "object",
    "properties": {
      "opportunity_id": { "type": "string" },
      "target_stage": {
        "type": "string",
        "enum": [
          "prospecting",
          "qualification",
          "proposal",
          "negotiation",
          "closed_won",
          "closed_lost"
        ]
      },
      "amount": { "type": "number", "minimum": 0 },
      "close_date": { "type": "string", "format": "date" },
      "win_probability": { "type": "number", "minimum": 0, "maximum": 100 }
    },
    "required": ["opportunity_id", "target_stage"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "medium",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "opportunity.advance_stage",
    "source_entity": "opportunity"
  }
}
```

## Constraints & Safety Notes
- **Idempotent**: moving to the same stage twice is a no-op
- **Stage transitions are validated**: can't skip stages or move backwards without explicit `revert_stage` intent
- `closed_won` and `closed_lost` are terminal stages
- `win_probability` is bounded 0–100
- High-value deals (amount > threshold) may require manager approval via a separate `opportunity.approve` action

## CRM: Sales Forecasting

Source: https://axag.org/docs/use-cases/crm/sales-forecasting

## Problem Statement
Generating a sales forecast aggregates pipeline data by period, stage, team, or product line. This is a read-only analytical operation with complex filter parameters.

## Why Human-Only Semantics Fail
- Forecast dashboards display charts that agents cannot parse
- Filter controls don't declare available dimensions or date ranges
- "Export" buttons produce files in undeclared formats
- Drill-down interactions are click-based with no declared navigation model

## Why Scraping Fails Here
- Charts render as SVG/Canvas — no textual data in the DOM
- Filters reload the page asynchronously
- Data tables are paginated with lazy loading
- Export downloads trigger browser file-save dialogs

## How AXAG Eliminates Scraping
`forecast.generate` declares the filter parameters, output format options, and scope boundaries. Agents get structured forecast data.

## Annotated UI Example
```html title="CRM — generate forecast"
<button
  axag-intent="forecast.generate"
  axag-entity="forecast"
  axag-action-type="read"
  axag-required-parameters='["period"]'
  axag-optional-parameters='["team_id","product_line","stage_filter","format"]'
  axag-scope="tenant"
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Generate a sales forecast for the specified period"
>Generate Forecast</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — forecast.generate" showLineNumbers
{
  "intent": "forecast.generate",
  "entity": "forecast",
  "action_type": "read",
  "operation_id": "forecast_generate",
  "description": "Generate a sales forecast for the specified period",
  "required_parameters": [
    {
      "name": "period",
      "type": "string",
      "enum": ["current_quarter", "next_quarter", "current_year", "custom"]
    }
  ],
  "optional_parameters": [
    { "name": "team_id", "type": "string" },
    { "name": "product_line", "type": "string" },
    {
      "name": "stage_filter",
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["prospecting", "qualification", "proposal", "negotiation", "closed_won"]
      }
    },
    { "name": "format", "type": "string", "enum": ["json", "csv", "pdf"], "default": "json" }
  ],
  "risk_level": "none",
  "idempotent": true,
  "scope": "tenant"
}
```

## Generated Tool Example
```json
{
  "name": "forecast_generate",
  "description": "Generate a sales forecast for the specified period",
  "input_schema": {
    "type": "object",
    "properties": {
      "period": {
        "type": "string",
        "enum": ["current_quarter", "next_quarter", "current_year", "custom"]
      },
      "team_id": { "type": "string" },
      "product_line": { "type": "string" },
      "stage_filter": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": ["prospecting", "qualification", "proposal", "negotiation", "closed_won"]
        }
      },
      "format": { "type": "string", "enum": ["json", "csv", "pdf"], "default": "json" }
    },
    "required": ["period"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "forecast.generate",
    "source_entity": "forecast"
  }
}
```

## Constraints & Safety Notes
- Read-only, no side-effects
- Scoped to tenant — cannot access other organizations' pipeline data
- `custom` period type would require additional `start_date`/`end_date` parameters
- CSV/PDF formats are for human consumption; JSON is the agent-preferred format


# Travel & Booking

## Travel: Search & Reservation

Source: https://axag.org/docs/use-cases/travel/search-and-reservation

## Problem Statement
Travel search involves querying availability across hotels, flights, or rental cars with dates, locations, guest counts, and preferences. Booking creates a reservation with financial commitment.

## Why Human-Only Semantics Fail
- Travel search forms have tightly coupled date pickers, location autocompletes, and guest counters
- Search results display pricing grids that vary by room type, fare class, etc.
- "Book Now" buttons don't declare the financial commitment amount
- Rate cards show "from $X" prices that differ from actual totals

## Why Scraping Fails Here
- Date pickers are calendar widgets with event-driven state
- Location autocompletes require typing and waiting for suggestions
- Pricing is dynamically calculated based on availability
- Booking requires session state (selected room, fare class, add-ons)
- Anti-bot protections on travel sites are extremely aggressive

## How AXAG Eliminates Scraping
`travel.search` and `travel.book` are separate intents. Search is read-only; booking is a write with financial side-effects and confirmation requirements.

## Annotated UI Example
```html title="Travel — search & book actions" showLineNumbers
<!-- Search -->
<button
  axag-intent="travel.search"
  axag-entity="travel_listing"
  axag-action-type="read"
  axag-required-parameters='["destination","check_in","check_out","guests"]'
  axag-optional-parameters='["property_type","price_max","amenities","sort_by"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Search for available travel accommodations"
>Search</button>

<!-- Book -->
<button
  axag-intent="travel.book"
  axag-entity="reservation"
  axag-action-type="write"
  axag-required-parameters='["listing_id","check_in","check_out","guests","payment_method_id"]'
  axag-optional-parameters='["special_requests","add_ons"]'
  axag-preconditions='["listing must be available for requested dates","payment method must be valid"]'
  axag-postconditions='["reservation created","payment authorized","confirmation email sent"]'
  axag-risk-level="critical"
  axag-confirmation-required="true"
  axag-approval-required="false"
  axag-idempotent="false"
  axag-side-effects='["payment_authorization","email_notification","availability_update"]'
  axag-description="Book a travel accommodation"
>Book Now</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — travel search + book" showLineNumbers
{
  "actions": [
    {
      "intent": "travel.search",
      "entity": "travel_listing",
      "action_type": "read",
      "operation_id": "travel_search",
      "description": "Search for available travel accommodations",
      "required_parameters": [
        { "name": "destination", "type": "string" },
        { "name": "check_in", "type": "string", "format": "date" },
        { "name": "check_out", "type": "string", "format": "date" },
        { "name": "guests", "type": "integer", "min": 1 }
      ],
      "optional_parameters": [
        {
          "name": "property_type",
          "type": "string",
          "enum": ["hotel", "apartment", "villa", "hostel"]
        },
        { "name": "price_max", "type": "number", "min": 0 },
        { "name": "amenities", "type": "array", "items": { "type": "string" } },
        {
          "name": "sort_by",
          "type": "string",
          "enum": ["price_asc", "price_desc", "rating", "distance"]
        }
      ],
      "risk_level": "none",
      "idempotent": true
    },
    {
      "intent": "travel.book",
      "entity": "reservation",
      "action_type": "write",
      "operation_id": "travel_book",
      "description": "Book a travel accommodation",
      "required_parameters": [
        { "name": "listing_id", "type": "string" },
        { "name": "check_in", "type": "string", "format": "date" },
        { "name": "check_out", "type": "string", "format": "date" },
        { "name": "guests", "type": "integer", "min": 1 },
        { "name": "payment_method_id", "type": "string" }
      ],
      "optional_parameters": [
        { "name": "special_requests", "type": "string" },
        { "name": "add_ons", "type": "array", "items": { "type": "string" } }
      ],
      "risk_level": "critical",
      "confirmation_required": true,
      "idempotent": false,
      "side_effects": ["payment_authorization", "email_notification", "availability_update"],
      "preconditions": [
        "listing must be available for requested dates",
        "payment method must be valid"
      ],
      "postconditions": ["reservation created", "payment authorized", "confirmation email sent"]
    }
  ]
}
```

## Constraints & Safety Notes
- **Search is safe**: read-only, idempotent, no risk
- **Booking is critical**: involves financial authorization
- Booking MUST require confirmation — agent cannot autonomously spend money
- `check_out` must be after `check_in`
- Booking is NOT idempotent — double-booking creates two reservations

## Travel: Booking Cancellation

Source: https://axag.org/docs/use-cases/travel/booking-cancellation

## Problem Statement
Cancelling a travel booking involves verifying the cancellation policy, calculating any penalties, and processing refunds. This is a destructive operation with financial implications.

## Why Human-Only Semantics Fail
- Cancellation policies are displayed as text paragraphs, not structured data
- Penalty amounts are calculated dynamically based on timing
- "Cancel Booking" doesn't declare whether refunds are automatic
- Free cancellation deadlines are shown as human-readable dates, not machine-checkable

## Why Scraping Fails Here
- Cancellation flows are behind authentication
- Policy text uses natural language without structured fields
- Penalty calculations require server-side computation
- Confirmation dialogs are JavaScript modals, not navigable pages

## How AXAG Eliminates Scraping
`booking.cancel` declares the operation's risk level, refund behavior, preconditions, and required confirmation.

## Annotated UI Example
```html title="Travel — booking cancellation ⚠️" showLineNumbers
<button
  axag-intent="booking.cancel"
  axag-entity="reservation"
  axag-action-type="delete"
  axag-required-parameters='["reservation_id"]'
  axag-optional-parameters='["reason"]'
  axag-preconditions='["reservation must exist","reservation must not be checked-in"]'
  axag-postconditions='["reservation cancelled","refund processed per cancellation policy"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["refund_processing","availability_release","cancellation_email"]'
  axag-description="Cancel an existing travel reservation"
>Cancel Booking</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — booking.cancel" showLineNumbers
{
  "intent": "booking.cancel",
  "entity": "reservation",
  "action_type": "delete",
  "operation_id": "booking_cancel",
  "description": "Cancel an existing travel reservation",
  "required_parameters": [{ "name": "reservation_id", "type": "string" }],
  "optional_parameters": [
    {
      "name": "reason",
      "type": "string",
      "enum": ["change_of_plans", "found_better_deal", "emergency", "other"]
    }
  ],
  "risk_level": "high",
  "confirmation_required": true,
  "idempotent": true,
  "side_effects": ["refund_processing", "availability_release", "cancellation_email"],
  "preconditions": ["reservation must exist", "reservation must not be checked-in"],
  "postconditions": ["reservation cancelled", "refund processed per cancellation policy"]
}
```

## Generated Tool Example
```json title="Tool — booking_cancel"
{
  "name": "booking_cancel",
  "description": "Cancel an existing travel reservation",
  "input_schema": {
    "type": "object",
    "properties": {
      "reservation_id": { "type": "string" },
      "reason": {
        "type": "string",
        "enum": ["change_of_plans", "found_better_deal", "emergency", "other"]
      }
    },
    "required": ["reservation_id"]
  },
  "metadata": {
    "action_type": "delete",
    "risk_level": "high",
    "idempotent": true,
    "confirmation_required": true,
    "approval_required": false,
    "side_effects": ["refund_processing", "availability_release", "cancellation_email"],
    "source_intent": "booking.cancel",
    "source_entity": "reservation"
  }
}
```

## Constraints & Safety Notes
- **High risk**: triggers refund/financial processing
- **Confirmation required**: agent MUST confirm with user
- **Idempotent**: cancelling an already-cancelled booking is a no-op
- Refund amount depends on timing relative to the cancellation policy window
- Reason is optional but helps with analytics


# Job Platforms

## Jobs: Job Search

Source: https://axag.org/docs/use-cases/jobs/job-search

## Problem Statement
Job search involves querying listings by keywords, location, experience level, salary range, and job type. Results need structured data including company, title, salary, and requirements.

## Why Human-Only Semantics Fail
- Job search forms mix free-text with structured filters
- Location fields use autocomplete with varying granularity (city/state/remote)
- Salary ranges are displayed in varied formats ("$80K-$120K", "Competitive")
- Experience levels use non-standard labels ("Mid-Senior", "Associate", "IC3")

## Why Scraping Fails Here
- Job board HTML varies dramatically between platforms
- Many listings lazy-load job details on click
- Salary data is often hidden or shown only after interaction
- Remote/hybrid/onsite flags are represented inconsistently

## How AXAG Eliminates Scraping
`job.search` declares structured parameters with enums for job type and experience, numeric ranges for salary, and standardized location handling.

## Annotated UI Example
```html title="Jobs — search listings"
<button
  axag-intent="job.search"
  axag-entity="job_listing"
  axag-action-type="read"
  axag-required-parameters='["query"]'
  axag-optional-parameters='["location","job_type","experience_level","salary_min","salary_max","remote","posted_within_days","page"]'
  axag-scope="public"
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Search for job listings matching criteria"
>Search Jobs</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — job.search" showLineNumbers
{
  "intent": "job.search",
  "entity": "job_listing",
  "action_type": "read",
  "operation_id": "job_search",
  "description": "Search for job listings matching criteria",
  "required_parameters": [{ "name": "query", "type": "string" }],
  "optional_parameters": [
    { "name": "location", "type": "string" },
    {
      "name": "job_type",
      "type": "string",
      "enum": ["full_time", "part_time", "contract", "internship", "freelance"]
    },
    {
      "name": "experience_level",
      "type": "string",
      "enum": ["entry", "mid", "senior", "lead", "executive"]
    },
    { "name": "salary_min", "type": "number", "min": 0 },
    { "name": "salary_max", "type": "number", "min": 0 },
    { "name": "remote", "type": "boolean" },
    { "name": "posted_within_days", "type": "integer", "min": 1 },
    { "name": "page", "type": "integer", "min": 1 }
  ],
  "risk_level": "none",
  "idempotent": true,
  "scope": "public"
}
```

## Generated Tool Example
```json title="Tool — job_search"
{
  "name": "job_search",
  "description": "Search for job listings matching criteria",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "location": { "type": "string" },
      "job_type": {
        "type": "string",
        "enum": ["full_time", "part_time", "contract", "internship", "freelance"]
      },
      "experience_level": {
        "type": "string",
        "enum": ["entry", "mid", "senior", "lead", "executive"]
      },
      "salary_min": { "type": "number", "minimum": 0 },
      "salary_max": { "type": "number", "minimum": 0 },
      "remote": { "type": "boolean" }
    },
    "required": ["query"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "job.search",
    "source_entity": "job_listing"
  }
}
```

## Constraints & Safety Notes
- Read-only, no side-effects
- Public scope — no authentication required for search
- Salary values are annual and in USD by default
- `posted_within_days` helps filter for freshness

## Jobs: Application Submission

Source: https://axag.org/docs/use-cases/jobs/application-submission

## Problem Statement
Submitting a job application involves attaching a resume, cover letter, answering screening questions, and providing personal details. This is a multi-part write operation with file uploads.

## Why Human-Only Semantics Fail
- Application forms vary wildly between companies (custom ATS forms)
- Screening questions are dynamically generated per job posting
- File upload controls don't declare accepted formats or size limits
- "Easy Apply" vs full application have different field requirements

## Why Scraping Fails Here
- Each ATS (Greenhouse, Lever, Workday) has completely different HTML
- File uploads require multipart form handling
- Screening questions are dynamically rendered based on the job ID
- CAPTCHA and bot detection protect application endpoints

## How AXAG Eliminates Scraping
`application.submit` declares the full parameter schema including file references, screening answers, and any required fields per posting.

## Annotated UI Example
```html title="Jobs — submit application" showLineNumbers
<button
  axag-intent="application.submit"
  axag-entity="application"
  axag-action-type="write"
  axag-required-parameters='["job_id","resume_url","first_name","last_name","email"]'
  axag-optional-parameters='["cover_letter_url","phone","linkedin_url","screening_answers","referral_source"]'
  axag-preconditions='["job listing must be active","user must not have already applied"]'
  axag-postconditions='["application submitted","confirmation email sent"]'
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-description="Submit a job application"
>Submit Application</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — application.submit" showLineNumbers
{
  "intent": "application.submit",
  "entity": "application",
  "action_type": "write",
  "operation_id": "application_submit",
  "description": "Submit a job application",
  "required_parameters": [
    { "name": "job_id", "type": "string" },
    { "name": "resume_url", "type": "string", "format": "url" },
    { "name": "first_name", "type": "string" },
    { "name": "last_name", "type": "string" },
    { "name": "email", "type": "string", "format": "email" }
  ],
  "optional_parameters": [
    { "name": "cover_letter_url", "type": "string", "format": "url" },
    { "name": "phone", "type": "string" },
    { "name": "linkedin_url", "type": "string", "format": "url" },
    {
      "name": "screening_answers",
      "type": "array",
      "items": {
        "type": "object",
        "properties": { "question_id": { "type": "string" }, "answer": { "type": "string" } }
      }
    },
    { "name": "referral_source", "type": "string" }
  ],
  "risk_level": "medium",
  "confirmation_required": true,
  "idempotent": false,
  "preconditions": ["job listing must be active", "user must not have already applied"],
  "postconditions": ["application submitted", "confirmation email sent"]
}
```

## Generated Tool Example
```json
{
  "name": "application_submit",
  "description": "Submit a job application",
  "input_schema": {
    "type": "object",
    "properties": {
      "job_id": { "type": "string" },
      "resume_url": { "type": "string", "format": "uri" },
      "first_name": { "type": "string" },
      "last_name": { "type": "string" },
      "email": { "type": "string", "format": "email" },
      "cover_letter_url": { "type": "string", "format": "uri" },
      "phone": { "type": "string" },
      "linkedin_url": { "type": "string", "format": "uri" },
      "screening_answers": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": { "question_id": { "type": "string" }, "answer": { "type": "string" } },
          "required": ["question_id", "answer"]
        }
      }
    },
    "required": ["job_id", "resume_url", "first_name", "last_name", "email"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "medium",
    "idempotent": false,
    "confirmation_required": true,
    "approval_required": false,
    "source_intent": "application.submit",
    "source_entity": "application"
  }
}
```

## Constraints & Safety Notes
- **Confirmation required**: submitting an application is a significant action
- **Not idempotent**: duplicate submissions may create duplicate applications
- Precondition prevents duplicate applications for the same job
- `resume_url` and `cover_letter_url` reference pre-uploaded files
- Screening answers must match the questions defined for the specific job listing

## Jobs: Interview Scheduling

Source: https://axag.org/docs/use-cases/jobs/interview-scheduling

## Problem Statement
Scheduling interviews requires coordinating availability between candidates and interviewers, selecting time slots, choosing interview format (video/phone/in-person), and sending calendar invitations.

## Why Human-Only Semantics Fail
- Calendar availability grids are visual components
- Time slot selection uses click-based interaction
- Interview format options don't declare their requirements (e.g., video link generation)
- "Confirm" sends calendar invites as a side-effect

## Why Scraping Fails Here
- Calendar components render as complex grid layouts
- Available slots are fetched dynamically via API
- Timezone handling varies between components
- Calendar invitations are sent server-side (iCal/Google Calendar API)

## How AXAG Eliminates Scraping
`interview.schedule` declares slot selection, format choice, and the side-effects of confirmation (calendar invite, notification).

## Annotated UI Example
```html title="Jobs — schedule interview" showLineNumbers
<button
  axag-intent="interview.schedule"
  axag-entity="interview"
  axag-action-type="write"
  axag-required-parameters='["application_id","slot_id","format"]'
  axag-optional-parameters='["interviewer_notes","candidate_timezone"]'
  axag-preconditions='["application must be in interview stage","slot must be available"]'
  axag-postconditions='["interview scheduled","calendar invites sent to all participants"]'
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["calendar_invite","email_notification"]'
  axag-description="Schedule an interview for a job application"
>Confirm Interview</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — interview.schedule" showLineNumbers
{
  "intent": "interview.schedule",
  "entity": "interview",
  "action_type": "write",
  "operation_id": "interview_schedule",
  "description": "Schedule an interview for a job application",
  "required_parameters": [
    { "name": "application_id", "type": "string" },
    { "name": "slot_id", "type": "string" },
    { "name": "format", "type": "string", "enum": ["video", "phone", "in_person"] }
  ],
  "optional_parameters": [
    { "name": "interviewer_notes", "type": "string" },
    { "name": "candidate_timezone", "type": "string" }
  ],
  "risk_level": "medium",
  "confirmation_required": true,
  "idempotent": true,
  "side_effects": ["calendar_invite", "email_notification"],
  "preconditions": ["application must be in interview stage", "slot must be available"],
  "postconditions": ["interview scheduled", "calendar invites sent to all participants"]
}
```

## Generated Tool Example
```json title="Tool — interview_schedule"
{
  "name": "interview_schedule",
  "description": "Schedule an interview for a job application",
  "input_schema": {
    "type": "object",
    "properties": {
      "application_id": { "type": "string" },
      "slot_id": { "type": "string" },
      "format": { "type": "string", "enum": ["video", "phone", "in_person"] },
      "interviewer_notes": { "type": "string" },
      "candidate_timezone": { "type": "string" }
    },
    "required": ["application_id", "slot_id", "format"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "medium",
    "idempotent": true,
    "confirmation_required": true,
    "approval_required": false,
    "side_effects": ["calendar_invite", "email_notification"],
    "source_intent": "interview.schedule",
    "source_entity": "interview"
  }
}
```

## Constraints & Safety Notes
- **Confirmation required**: scheduling sends calendar invites to external participants
- **Idempotent**: re-scheduling to the same slot is a no-op
- Side-effects include external notifications (can't be silently tested)
- `video` format auto-generates a meeting link as part of the postcondition
- Candidate timezone is used to display correct times in the invite


# Analytics & BI

## Analytics: Dashboard Filtering

Source: https://axag.org/docs/use-cases/analytics/dashboard-filtering

## Problem Statement
Analytics dashboards let users filter data by date range, dimensions, metrics, and segments. Agents need to read filtered data programmatically without interacting with visual filter controls.

## Why Human-Only Semantics Fail
- Filter panels use date pickers, dropdowns, and multi-selects
- Available dimensions/metrics aren't declared — they depend on the dataset
- Dashboard state is stored in the URL query string or session, not the DOM
- "Apply Filters" triggers a re-render, not a navigable form submission

## Why Scraping Fails Here
- Dashboard charts render as Canvas/SVG — data is not in the DOM
- Filter state is managed in JavaScript memory
- Real-time dashboards update via WebSocket
- Each visualization library (D3, Chart.js, Highcharts) has different DOM output

## How AXAG Eliminates Scraping
`dashboard.filter` declares available filter parameters, valid date ranges, and output format. Agents get structured data instead of parsing chart SVGs.

## Annotated UI Example
```html title="Analytics — dashboard filter"
<button
  axag-intent="dashboard.filter"
  axag-entity="dashboard"
  axag-action-type="read"
  axag-required-parameters='["dashboard_id"]'
  axag-optional-parameters='["date_range","dimensions","metrics","segment_id","granularity"]'
  axag-scope="tenant"
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Retrieve filtered dashboard data"
>Apply Filters</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — dashboard.filter" showLineNumbers
{
  "intent": "dashboard.filter",
  "entity": "dashboard",
  "action_type": "read",
  "operation_id": "dashboard_filter",
  "description": "Retrieve filtered dashboard data",
  "required_parameters": [{ "name": "dashboard_id", "type": "string" }],
  "optional_parameters": [
    {
      "name": "date_range",
      "type": "object",
      "properties": {
        "start": { "type": "string", "format": "date" },
        "end": { "type": "string", "format": "date" }
      }
    },
    { "name": "dimensions", "type": "array", "items": { "type": "string" } },
    { "name": "metrics", "type": "array", "items": { "type": "string" } },
    { "name": "segment_id", "type": "string" },
    {
      "name": "granularity",
      "type": "string",
      "enum": ["hourly", "daily", "weekly", "monthly", "quarterly", "yearly"]
    }
  ],
  "risk_level": "none",
  "idempotent": true,
  "scope": "tenant"
}
```

## Generated Tool Example
```json
{
  "name": "dashboard_filter",
  "description": "Retrieve filtered dashboard data",
  "input_schema": {
    "type": "object",
    "properties": {
      "dashboard_id": { "type": "string" },
      "date_range": {
        "type": "object",
        "properties": {
          "start": { "type": "string", "format": "date" },
          "end": { "type": "string", "format": "date" }
        }
      },
      "dimensions": { "type": "array", "items": { "type": "string" } },
      "metrics": { "type": "array", "items": { "type": "string" } },
      "granularity": {
        "type": "string",
        "enum": ["hourly", "daily", "weekly", "monthly", "quarterly", "yearly"]
      }
    },
    "required": ["dashboard_id"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "dashboard.filter",
    "source_entity": "dashboard"
  }
}
```

## Constraints & Safety Notes
- Read-only, no side-effects
- Scoped to tenant — users can only access their organization's dashboards
- Available dimensions and metrics depend on the specific dashboard/dataset
- Granularity affects data aggregation level

## Analytics: Report Generation

Source: https://axag.org/docs/use-cases/analytics/report-generation

## Problem Statement
Generating reports involves selecting data sources, date ranges, metrics, and output format. Reports may take time to process (async) and produce downloadable files.

## Why Human-Only Semantics Fail
- Report builder UIs are multi-step wizards
- Available metrics depend on selected data sources
- Output format options (PDF, CSV, XLSX) aren't declared as parameters
- Processing time is shown with spinners, not structured status

## Why Scraping Fails Here
- Report generation is asynchronous — results aren't immediate
- Download links are temporary, signed URLs
- Complex reports trigger server-side processing jobs
- Progress indicators are JavaScript-driven animations

## How AXAG Eliminates Scraping
`report.generate` declares it as an async operation with a defined output format enum. Agents poll for completion using `report.status`.

## Annotated UI Example
```html title="Analytics — generate report (async)"
<button
  axag-intent="report.generate"
  axag-entity="report"
  axag-action-type="write"
  axag-required-parameters='["report_type","date_range"]'
  axag-optional-parameters='["metrics","dimensions","format","filters"]'
  axag-postconditions='["report generation job created"]'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-async="true"
  axag-scope="tenant"
  axag-description="Generate an analytics report"
>Generate Report</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — report.generate" showLineNumbers
{
  "intent": "report.generate",
  "entity": "report",
  "action_type": "write",
  "operation_id": "report_generate",
  "description": "Generate an analytics report",
  "required_parameters": [
    {
      "name": "report_type",
      "type": "string",
      "enum": ["summary", "detailed", "comparison", "trend"]
    },
    {
      "name": "date_range",
      "type": "object",
      "properties": {
        "start": { "type": "string", "format": "date" },
        "end": { "type": "string", "format": "date" }
      }
    }
  ],
  "optional_parameters": [
    { "name": "metrics", "type": "array", "items": { "type": "string" } },
    { "name": "dimensions", "type": "array", "items": { "type": "string" } },
    {
      "name": "format",
      "type": "string",
      "enum": ["pdf", "csv", "xlsx", "json"],
      "default": "json"
    },
    { "name": "filters", "type": "object" }
  ],
  "risk_level": "low",
  "idempotent": false,
  "async": true,
  "scope": "tenant",
  "postconditions": ["report generation job created"]
}
```

## Generated Tool Example
```json
{
  "name": "report_generate",
  "description": "Generate an analytics report (async — returns job ID)",
  "input_schema": {
    "type": "object",
    "properties": {
      "report_type": { "type": "string", "enum": ["summary", "detailed", "comparison", "trend"] },
      "date_range": {
        "type": "object",
        "properties": {
          "start": { "type": "string", "format": "date" },
          "end": { "type": "string", "format": "date" }
        },
        "required": ["start", "end"]
      },
      "metrics": { "type": "array", "items": { "type": "string" } },
      "format": { "type": "string", "enum": ["pdf", "csv", "xlsx", "json"], "default": "json" }
    },
    "required": ["report_type", "date_range"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "low",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "async": true,
    "source_intent": "report.generate",
    "source_entity": "report"
  }
}
```

## Constraints & Safety Notes
- **Async operation**: returns a job ID, not the report itself
- Agent should poll `report.status` with the job ID to check completion
- Not idempotent — each call creates a new report job
- `json` is the preferred agent format; PDF/XLSX are for human consumption
- Scoped to tenant data only

## Analytics: Dataset Export

Source: https://axag.org/docs/use-cases/analytics/dataset-export

## Problem Statement
Exporting raw datasets lets users download filtered data for external analysis. Exports may be large (millions of rows) and require async processing with size/row limits.

## Why Human-Only Semantics Fail
- "Export" buttons don't declare file format, row limits, or processing time
- Column selection is done via checkbox lists with no schema
- Large exports show progress bars with no structured status
- Download links expire without declaring TTL

## Why Scraping Fails Here
- Export triggers a server-side job, not a synchronous download
- Download URLs are signed and time-limited
- Large files require streaming — not available in DOM
- Column names in the UI may differ from the export output

## How AXAG Eliminates Scraping
`dataset.export` declares column selection, row limits, format options, and the async nature of the operation.

## Annotated UI Example
```html title="Analytics — dataset export (async)"
<button
  axag-intent="dataset.export"
  axag-entity="dataset"
  axag-action-type="read"
  axag-required-parameters='["dataset_id"]'
  axag-optional-parameters='["columns","filters","format","row_limit"]'
  axag-postconditions='["export job created","download link available when complete"]'
  axag-risk-level="none"
  axag-idempotent="false"
  axag-async="true"
  axag-scope="tenant"
  axag-description="Export a dataset as a downloadable file"
>Export Data</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — dataset.export" showLineNumbers
{
  "intent": "dataset.export",
  "entity": "dataset",
  "action_type": "read",
  "operation_id": "dataset_export",
  "description": "Export a dataset as a downloadable file",
  "required_parameters": [{ "name": "dataset_id", "type": "string" }],
  "optional_parameters": [
    {
      "name": "columns",
      "type": "array",
      "description": "Columns to include; defaults to all",
      "items": { "type": "string" }
    },
    { "name": "filters", "type": "object" },
    { "name": "format", "type": "string", "enum": ["csv", "json", "parquet"], "default": "csv" },
    { "name": "row_limit", "type": "integer", "min": 1, "max": 10000000, "default": 100000 }
  ],
  "risk_level": "none",
  "idempotent": false,
  "async": true,
  "scope": "tenant",
  "postconditions": ["export job created", "download link available when complete"]
}
```

## Generated Tool Example
```json
{
  "name": "dataset_export",
  "description": "Export a dataset as a downloadable file (async — returns job ID)",
  "input_schema": {
    "type": "object",
    "properties": {
      "dataset_id": { "type": "string" },
      "columns": { "type": "array", "items": { "type": "string" } },
      "filters": { "type": "object" },
      "format": { "type": "string", "enum": ["csv", "json", "parquet"], "default": "csv" },
      "row_limit": { "type": "integer", "minimum": 1, "maximum": 10000000, "default": 100000 }
    },
    "required": ["dataset_id"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "async": true,
    "source_intent": "dataset.export",
    "source_entity": "dataset"
  }
}
```

## Constraints & Safety Notes
- Read-only operation despite being async
- Row limit defaults to 100K, max 10M to prevent abuse
- `parquet` format is efficient for large datasets and agent consumption
- Download links from the completed job have a TTL (typically 24 hours)
- Scoped to tenant data


# Customer Support

## Support: Ticket Creation

Source: https://axag.org/docs/use-cases/support/ticket-creation

## Problem Statement
Creating a support ticket involves categorizing the issue, providing a description, setting priority, and optionally attaching files. This is a write operation that triggers routing and SLA timers.

## Why Human-Only Semantics Fail
- Category dropdowns have nested hierarchies not reflected in the DOM
- Priority labels ("Urgent", "High") don't map to SLA definitions
- File attachment controls don't declare accepted types or size limits
- "Submit Ticket" doesn't declare the routing side-effects

## Why Scraping Fails Here
- Support portals are behind authentication
- Category trees are lazily loaded
- Rich text description fields use WYSIWYG editors
- Ticket confirmation pages are dynamically rendered

## How AXAG Eliminates Scraping
`ticket.create` declares categories as enums, priority levels with semantic meaning, and the side-effects of creation (routing, SLA timer start).

## Annotated UI Example
```html title="Support — create ticket"
<button
  axag-intent="ticket.create"
  axag-entity="ticket"
  axag-action-type="write"
  axag-required-parameters='["subject","description","category","priority"]'
  axag-optional-parameters='["attachment_urls","tags","cc_emails"]'
  axag-postconditions='["ticket created","routing rules applied","SLA timer started"]'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-scope="tenant"
  axag-description="Create a new support ticket"
>Submit Ticket</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — ticket.create" showLineNumbers
{
  "intent": "ticket.create",
  "entity": "ticket",
  "action_type": "write",
  "operation_id": "ticket_create",
  "description": "Create a new support ticket",
  "required_parameters": [
    { "name": "subject", "type": "string", "maxLength": 200 },
    { "name": "description", "type": "string", "maxLength": 10000 },
    {
      "name": "category",
      "type": "string",
      "enum": ["billing", "technical", "account", "feature_request", "bug_report", "other"]
    },
    { "name": "priority", "type": "string", "enum": ["low", "medium", "high", "urgent"] }
  ],
  "optional_parameters": [
    { "name": "attachment_urls", "type": "array", "items": { "type": "string", "format": "uri" } },
    { "name": "tags", "type": "array", "items": { "type": "string" } },
    { "name": "cc_emails", "type": "array", "items": { "type": "string", "format": "email" } }
  ],
  "risk_level": "low",
  "idempotent": false,
  "scope": "tenant",
  "postconditions": ["ticket created", "routing rules applied", "SLA timer started"]
}
```

## Generated Tool Example
```json title="Tool — ticket_create"
{
  "name": "ticket_create",
  "description": "Create a new support ticket",
  "input_schema": {
    "type": "object",
    "properties": {
      "subject": { "type": "string", "maxLength": 200 },
      "description": { "type": "string", "maxLength": 10000 },
      "category": {
        "type": "string",
        "enum": ["billing", "technical", "account", "feature_request", "bug_report", "other"]
      },
      "priority": { "type": "string", "enum": ["low", "medium", "high", "urgent"] },
      "attachment_urls": { "type": "array", "items": { "type": "string", "format": "uri" } },
      "tags": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["subject", "description", "category", "priority"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "low",
    "idempotent": false,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "ticket.create",
    "source_entity": "ticket"
  }
}
```

## Constraints & Safety Notes
- **Not idempotent**: duplicate submissions create duplicate tickets
- Low risk — creates a ticket but doesn't modify existing data
- SLA timer starts immediately upon creation based on priority level
- Routing rules assign the ticket to the appropriate team
- `urgent` priority may trigger immediate page/notification to on-call staff

## Support: Ticket Escalation

Source: https://axag.org/docs/use-cases/support/escalation

## Problem Statement
Escalating a support ticket transfers it to a higher-tier team with a reason and urgency level. This changes the ticket's priority, assignment, and SLA, and may notify management.

## Why Human-Only Semantics Fail
- "Escalate" buttons don't declare what team the ticket moves to
- Escalation reasons are free-text with no declared categories
- The impact on SLA (reset, tighten) is not communicated
- Manager notification is a hidden side-effect

## Why Scraping Fails Here
- Escalation dialogs are modal popups
- Team assignment logic is server-side
- Notification recipients are determined by business rules, not the DOM
- Escalation history is in a collapsible panel that may not be rendered

## How AXAG Eliminates Scraping
`ticket.escalate` declares the reason enum, target tier, and all side-effects (SLA update, notifications).

## Annotated UI Example
```html title="Support — ticket escalation ⚠️" showLineNumbers
<button
  axag-intent="ticket.escalate"
  axag-entity="ticket"
  axag-action-type="write"
  axag-required-parameters='["ticket_id","reason"]'
  axag-optional-parameters='["target_tier","urgency_override","notes"]'
  axag-preconditions='["ticket must be open","user must have escalation permission"]'
  axag-postconditions='["ticket escalated","SLA updated","manager notified"]'
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-side-effects='["sla_update","manager_notification","assignment_change"]'
  axag-description="Escalate a support ticket to a higher-tier team"
>Escalate</button>
```

## Semantic Manifest Excerpt
```json title="Manifest — ticket.escalate" showLineNumbers
{
  "intent": "ticket.escalate",
  "entity": "ticket",
  "action_type": "write",
  "operation_id": "ticket_escalate",
  "description": "Escalate a support ticket to a higher-tier team",
  "required_parameters": [
    { "name": "ticket_id", "type": "string" },
    {
      "name": "reason",
      "type": "string",
      "enum": [
        "customer_request",
        "technical_complexity",
        "sla_risk",
        "vip_customer",
        "unresolved",
        "other"
      ]
    }
  ],
  "optional_parameters": [
    {
      "name": "target_tier",
      "type": "string",
      "enum": ["tier_2", "tier_3", "engineering", "management"]
    },
    { "name": "urgency_override", "type": "string", "enum": ["high", "urgent", "critical"] },
    { "name": "notes", "type": "string", "maxLength": 2000 }
  ],
  "risk_level": "medium",
  "confirmation_required": true,
  "idempotent": false,
  "side_effects": ["sla_update", "manager_notification", "assignment_change"],
  "preconditions": ["ticket must be open", "user must have escalation permission"],
  "postconditions": ["ticket escalated", "SLA updated", "manager notified"]
}
```

## Generated Tool Example
```json
{
  "name": "ticket_escalate",
  "description": "Escalate a support ticket to a higher-tier team",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticket_id": { "type": "string" },
      "reason": {
        "type": "string",
        "enum": [
          "customer_request",
          "technical_complexity",
          "sla_risk",
          "vip_customer",
          "unresolved",
          "other"
        ]
      },
      "target_tier": { "type": "string", "enum": ["tier_2", "tier_3", "engineering", "management"] },
      "urgency_override": { "type": "string", "enum": ["high", "urgent", "critical"] },
      "notes": { "type": "string", "maxLength": 2000 }
    },
    "required": ["ticket_id", "reason"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "medium",
    "idempotent": false,
    "confirmation_required": true,
    "approval_required": false,
    "side_effects": ["sla_update", "manager_notification", "assignment_change"],
    "source_intent": "ticket.escalate",
    "source_entity": "ticket"
  }
}
```

## Constraints & Safety Notes
- **Confirmation required**: escalation notifies management and changes SLA
- **Not idempotent**: escalating twice creates two escalation events
- Requires `escalation_permission` — not all agents/users can escalate
- `urgency_override` can override the existing ticket priority
- Manager notification is an automatic side-effect that cannot be suppressed


# Enterprise & SaaS

## Enterprise: CRUD Dashboard

Source: https://axag.org/docs/use-cases/enterprise/crud-dashboard

## Problem Statement
Enterprise CRUD dashboards are the backbone of internal tools — managing users, products, configurations, and records. Agents need to perform create, read, update, and delete operations across diverse entity types with role-based access.

## Why Human-Only Semantics Fail
- CRUD tables use DataGrid components with inline editing
- Column sorting, filtering, and pagination are interactive but undeclared
- "Edit" and "Delete" buttons on each row don't declare the entity or record ID
- Bulk operations (select all + delete) have no declared safety boundaries

## Why Scraping Fails Here
- DataGrid components virtualize rows (only visible rows are in the DOM)
- Inline edit mode changes the DOM structure dynamically
- Pagination may use cursor-based pagination with no page count
- Role-based visibility hides columns/buttons that aren't in the DOM at all

## How AXAG Eliminates Scraping
Each CRUD operation is annotated with entity type, parameters, risk level, and role requirements. Agents use the generated tools without parsing table DOM.

## Annotated UI Examples
```html
<!-- List / Read -->
<button
  axag-intent="entity.list"
  axag-entity="user"
  axag-action-type="read"
  axag-required-parameters='[]'
  axag-optional-parameters='["page","page_size","sort_by","sort_order","filters"]'
  axag-scope="tenant"
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="List users with optional filtering and pagination"
>View Users</button>

<!-- Create -->
<button
  axag-intent="entity.create"
  axag-entity="user"
  axag-action-type="write"
  axag-required-parameters='["email","role"]'
  axag-optional-parameters='["first_name","last_name","department","phone"]'
  axag-preconditions='["caller must have user_admin role"]'
  axag-postconditions='["user created","welcome email sent"]'
  axag-risk-level="medium"
  axag-idempotent="false"
  axag-scope="tenant"
  axag-description="Create a new user in the system"
>Add User</button>

<!-- Update -->
<button
  axag-intent="entity.update"
  axag-entity="user"
  axag-action-type="write"
  axag-required-parameters='["user_id"]'
  axag-optional-parameters='["email","role","first_name","last_name","department","status"]'
  axag-preconditions='["caller must have user_admin role","user must exist"]'
  axag-risk-level="medium"
  axag-idempotent="true"
  axag-scope="tenant"
  axag-description="Update an existing user record"
>Edit User</button>

<!-- Delete -->
<button
  axag-intent="entity.delete"
  axag-entity="user"
  axag-action-type="delete"
  axag-required-parameters='["user_id"]'
  axag-preconditions='["caller must have user_admin role","user must not have active sessions"]'
  axag-postconditions='["user deactivated","sessions invalidated"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-scope="tenant"
  axag-description="Delete (deactivate) a user from the system"
>Delete User</button>
```

## Generated Tool Examples
```json
[
  {
    "name": "user_list",
    "description": "List users with optional filtering and pagination",
    "input_schema": {
      "type": "object",
      "properties": {
        "page": { "type": "integer", "minimum": 1 },
        "page_size": { "type": "integer", "minimum": 1, "maximum": 100 },
        "sort_by": { "type": "string" },
        "sort_order": { "type": "string", "enum": ["asc", "desc"] },
        "filters": { "type": "object" }
      },
      "required": []
    },
    "metadata": {
      "action_type": "read",
      "risk_level": "none",
      "idempotent": true,
      "confirmation_required": false,
      "approval_required": false,
      "source_intent": "user.list",
      "source_entity": "user"
    }
  },
  {
    "name": "user_create",
    "description": "Create a new user in the system",
    "input_schema": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "role": { "type": "string", "enum": ["viewer", "editor", "admin"] },
        "first_name": { "type": "string" },
        "last_name": { "type": "string" }
      },
      "required": ["email", "role"]
    },
    "metadata": {
      "action_type": "read",
      "risk_level": "medium",
      "idempotent": false,
      "confirmation_required": false,
      "approval_required": false,
      "source_intent": "user.create",
      "source_entity": "user"
    }
  },
  {
    "name": "user_delete",
    "description": "Delete (deactivate) a user from the system",
    "input_schema": {
      "type": "object",
      "properties": { "user_id": { "type": "string" } },
      "required": ["user_id"]
    },
    "metadata": {
      "action_type": "read",
      "risk_level": "high",
      "idempotent": true,
      "confirmation_required": true,
      "approval_required": false,
      "source_intent": "user.delete",
      "source_entity": "user"
    }
  }
]
```

## Constraints & Safety Notes
- All operations scoped to tenant — no cross-tenant access
- Delete is "soft delete" (deactivation), hence idempotent
- Create requires `user_admin` role
- Delete requires confirmation and invalidates active sessions
- List supports flexible filtering via a generic `filters` object

## Enterprise: Admin-Guarded Actions

Source: https://axag.org/docs/use-cases/enterprise/admin-guarded-actions

## Problem Statement
Certain enterprise operations (changing billing plans, modifying security settings, enabling integrations) require administrative privileges. These actions must declare their permission requirements so agents don't attempt unauthorized operations.

## Why Human-Only Semantics Fail
- Admin-only buttons look identical to regular buttons
- Permission requirements are enforced server-side with no client-side declaration
- Role hierarchies (viewer < editor < admin < super-admin) aren't in the DOM
- Failed permission checks return generic "Forbidden" errors

## Why Scraping Fails Here
- Admin UI sections may be entirely absent from non-admin DOM
- Permission checks happen via API, not DOM visibility
- Multi-factor authentication gates are JavaScript-driven
- Admin panels often have different URL structures

## How AXAG Eliminates Scraping
Admin-guarded actions declare `axag-required-roles` and `axag-preconditions` with specific permission requirements. Agents check role compatibility before attempting the action.

## Annotated UI Example
```html
<!-- Change Billing Plan -->
<button
  axag-intent="billing.change_plan"
  axag-entity="billing"
  axag-action-type="write"
  axag-required-parameters='["plan_id"]'
  axag-optional-parameters='["billing_cycle","promo_code"]'
  axag-preconditions='["caller must have billing_admin role","account must not have past-due invoices"]'
  axag-postconditions='["plan changed","prorated charges applied","confirmation email sent"]'
  axag-risk-level="critical"
  axag-confirmation-required="true"
  axag-approval-required="true"
  axag-approval-roles='["super_admin"]'
  axag-idempotent="true"
  axag-side-effects='["billing_change","proration","email_notification"]'
  axag-scope="tenant"
  axag-description="Change the organization's billing plan"
>Change Plan</button>

<!-- Disable MFA (Security Setting) -->
<button
  axag-intent="security.disable_mfa"
  axag-entity="security_settings"
  axag-action-type="write"
  axag-required-parameters='["user_id"]'
  axag-preconditions='["caller must have security_admin role","MFA must be currently enabled"]'
  axag-postconditions='["MFA disabled for user","security audit log updated"]'
  axag-risk-level="critical"
  axag-confirmation-required="true"
  axag-approval-required="true"
  axag-approval-roles='["security_admin","super_admin"]'
  axag-idempotent="true"
  axag-side-effects='["security_posture_change","audit_log"]'
  axag-scope="tenant"
  axag-description="Disable multi-factor authentication for a user"
>Disable MFA</button>
```

## Semantic Manifest Excerpt
```json
{
  "intent": "billing.change_plan",
  "entity": "billing",
  "action_type": "write",
  "operation_id": "billing_change_plan",
  "description": "Change the organization's billing plan",
  "required_parameters": [{ "name": "plan_id", "type": "string" }],
  "optional_parameters": [
    { "name": "billing_cycle", "type": "string", "enum": ["monthly", "annual"] },
    { "name": "promo_code", "type": "string" }
  ],
  "risk_level": "critical",
  "confirmation_required": true,
  "approval_required": true,
  "approval_roles": ["super_admin"],
  "idempotent": true,
  "scope": "tenant",
  "side_effects": ["billing_change", "proration", "email_notification"],
  "preconditions": [
    "caller must have billing_admin role",
    "account must not have past-due invoices"
  ],
  "postconditions": ["plan changed", "prorated charges applied", "confirmation email sent"]
}
```

## Constraints & Safety Notes
- **Critical risk**: billing changes have immediate financial impact
- **Dual gate**: requires both confirmation AND approval from a super_admin
- Agents MUST check preconditions before attempting: verify role, verify no past-due invoices
- Disabling MFA is a security-sensitive operation that logs to audit trail
- Both actions are idempotent (changing to the same plan, disabling already-disabled MFA)
- `approval_roles` declares WHO can approve, not just that approval is needed

## Enterprise: Multi-Step Approval

Source: https://axag.org/docs/use-cases/enterprise/multi-step-approval

## Problem Statement
Enterprise workflows often require sequential approvals from multiple stakeholders (e.g., purchase requisition → manager → finance → procurement). Agents need to understand the approval chain, current status, and their role in the flow.

## Why Human-Only Semantics Fail
- Approval workflows are displayed as visual timelines or Kanban boards
- "Approve" buttons don't declare which step they advance to
- The complete approval chain is not visible from a single view
- Conditional branching (amount > $10K → needs VP approval) is business logic, not UI

## Why Scraping Fails Here
- Workflow state is server-managed, not in the DOM
- Approval history is in collapsible panels
- The next approver is determined by business rules
- Email-based approvals happen outside the web UI entirely

## How AXAG Eliminates Scraping
`approval.submit`, `approval.approve`, and `approval.reject` are distinct intents with declared chain position, required fields per step, and role requirements.

## Annotated UI Example
```html title="Enterprise — submit / approve / reject workflow" showLineNumbers
<!-- Submit for Approval -->
<button
  axag-intent="approval.submit"
  axag-entity="purchase_requisition"
  axag-action-type="write"
  axag-required-parameters='["requisition_id"]'
  axag-optional-parameters='["justification","urgency"]'
  axag-preconditions='["requisition must be in draft status","all required fields must be populated"]'
  axag-postconditions='["requisition submitted for approval","first approver notified"]'
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["email_notification_to_approver"]'
  axag-description="Submit a purchase requisition for approval"
>Submit for Approval</button>

<!-- Approve -->
<button
  axag-intent="approval.approve"
  axag-entity="purchase_requisition"
  axag-action-type="write"
  axag-required-parameters='["requisition_id","approval_step_id"]'
  axag-optional-parameters='["comments","conditions"]'
  axag-preconditions='["caller must be the designated approver for current step","requisition must be pending at this step"]'
  axag-postconditions='["step approved","next approver notified or workflow complete"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["workflow_advancement","notification"]'
  axag-description="Approve a purchase requisition at the current approval step"
>Approve</button>

<!-- Reject -->
<button
  axag-intent="approval.reject"
  axag-entity="purchase_requisition"
  axag-action-type="write"
  axag-required-parameters='["requisition_id","approval_step_id","reason"]'
  axag-preconditions='["caller must be the designated approver for current step"]'
  axag-postconditions='["requisition rejected","submitter notified"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["workflow_termination","notification"]'
  axag-description="Reject a purchase requisition at the current approval step"
>Reject</button>
```

## Approval Chain Schema
```json title="Approval chain schema"
{
  "approval_chain": [
    { "step": 1, "role": "manager", "condition": "always" },
    { "step": 2, "role": "finance", "condition": "amount > 1000" },
    { "step": 3, "role": "vp", "condition": "amount > 10000" },
    { "step": 4, "role": "procurement", "condition": "always" }
  ]
}
```

## Generated Tool Examples
```json title="Tools — submit / approve / reject" showLineNumbers
[
  {
    "name": "approval_submit",
    "description": "Submit a purchase requisition for approval",
    "input_schema": {
      "type": "object",
      "properties": {
        "requisition_id": { "type": "string" },
        "justification": { "type": "string" },
        "urgency": { "type": "string", "enum": ["normal", "high", "critical"] }
      },
      "required": ["requisition_id"]
    },
    "metadata": {
      "action_type": "read",
      "risk_level": "medium",
      "idempotent": true,
      "confirmation_required": true,
      "approval_required": false,
      "source_intent": "approval.submit",
      "source_entity": "approval"
    }
  },
  {
    "name": "approval_approve",
    "description": "Approve a purchase requisition at the current step",
    "input_schema": {
      "type": "object",
      "properties": {
        "requisition_id": { "type": "string" },
        "approval_step_id": { "type": "string" },
        "comments": { "type": "string" },
        "conditions": { "type": "string" }
      },
      "required": ["requisition_id", "approval_step_id"]
    },
    "metadata": {
      "action_type": "read",
      "risk_level": "high",
      "idempotent": true,
      "confirmation_required": true,
      "approval_required": false,
      "source_intent": "approval.approve",
      "source_entity": "approval"
    }
  },
  {
    "name": "approval_reject",
    "description": "Reject a purchase requisition at the current step",
    "input_schema": {
      "type": "object",
      "properties": {
        "requisition_id": { "type": "string" },
        "approval_step_id": { "type": "string" },
        "reason": { "type": "string" }
      },
      "required": ["requisition_id", "approval_step_id", "reason"]
    },
    "metadata": {
      "action_type": "read",
      "risk_level": "high",
      "idempotent": true,
      "confirmation_required": true,
      "approval_required": false,
      "source_intent": "approval.reject",
      "source_entity": "approval"
    }
  }
]
```

## Constraints & Safety Notes
- All approval operations are **idempotent**: approving an already-approved step is a no-op
- **Role-gated**: only the designated approver for the current step can approve/reject
- Conditional steps (amount thresholds) are evaluated server-side
- Rejection terminates the workflow and notifies the submitter
- Approval with `conditions` creates a conditional approval that may require follow-up

## Enterprise: Tenant-Scoped Admin

Source: https://axag.org/docs/use-cases/enterprise/tenant-scoped-admin

## Problem Statement
Multi-tenant SaaS platforms require strict data isolation. Admin operations must be scoped to the current tenant, and agents must never access, modify, or even reference data from other tenants.

## Why Human-Only Semantics Fail
- Tenant context is stored in cookies/headers, not declared in the UI
- Admin panels don't show which tenant they operate on
- "Switch Organization" controls don't declare the scoping implications
- Cross-tenant operations have identical UI to same-tenant operations

## Why Scraping Fails Here
- Tenant ID is in JWT tokens or session state, not the DOM
- URL patterns may or may not include tenant identifiers
- Admin UIs are identical across tenants — only the data differs
- Cross-tenant access bugs are the #1 SaaS security vulnerability

## How AXAG Eliminates Scraping
`axag-scope="tenant"` and `axag-tenant-boundary="strict"` declare that every operation is tenant-scoped. Generated tools include tenant context automatically.

## Annotated UI Example
```html
<!-- Tenant-Scoped User Management -->
<button
  axag-intent="admin.list_users"
  axag-entity="user"
  axag-action-type="read"
  axag-required-parameters='[]'
  axag-optional-parameters='["role_filter","status_filter","page","page_size"]'
  axag-scope="tenant"
  axag-tenant-boundary="strict"
  axag-preconditions='["caller must have tenant_admin role"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="List all users in the current tenant"
>Manage Users</button>

<!-- Tenant Settings -->
<button
  axag-intent="admin.update_tenant_settings"
  axag-entity="tenant_settings"
  axag-action-type="write"
  axag-required-parameters='["setting_key","setting_value"]'
  axag-preconditions='["caller must have tenant_admin role"]'
  axag-postconditions='["setting updated","audit log entry created"]'
  axag-scope="tenant"
  axag-tenant-boundary="strict"
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["audit_log","setting_propagation"]'
  axag-description="Update a tenant-level configuration setting"
>Save Settings</button>

<!-- Tenant Data Export (Compliance) -->
<button
  axag-intent="admin.export_tenant_data"
  axag-entity="tenant_data"
  axag-action-type="read"
  axag-required-parameters='["export_type"]'
  axag-optional-parameters='["date_range","format"]'
  axag-preconditions='["caller must have tenant_admin role","export must comply with data retention policy"]'
  axag-postconditions='["export job created"]'
  axag-scope="tenant"
  axag-tenant-boundary="strict"
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-async="true"
  axag-description="Export all tenant data for compliance or migration purposes"
>Export Tenant Data</button>
```

## Semantic Manifest Excerpt
```json
{
  "tenant_boundary": "strict",
  "scope": "tenant",
  "actions": [
    {
      "intent": "admin.list_users",
      "entity": "user",
      "action_type": "read",
      "operation_id": "admin_list_users",
      "description": "List all users in the current tenant",
      "required_parameters": [],
      "optional_parameters": [
        { "name": "role_filter", "type": "string" },
        { "name": "status_filter", "type": "string", "enum": ["active", "inactive", "suspended"] },
        { "name": "page", "type": "integer", "min": 1 },
        { "name": "page_size", "type": "integer", "min": 1, "max": 100 }
      ],
      "risk_level": "none",
      "idempotent": true,
      "preconditions": ["caller must have tenant_admin role"]
    },
    {
      "intent": "admin.update_tenant_settings",
      "entity": "tenant_settings",
      "action_type": "write",
      "operation_id": "admin_update_tenant_settings",
      "description": "Update a tenant-level configuration setting",
      "required_parameters": [
        { "name": "setting_key", "type": "string" },
        { "name": "setting_value", "type": "string" }
      ],
      "optional_parameters": [],
      "risk_level": "high",
      "confirmation_required": true,
      "idempotent": true,
      "side_effects": ["audit_log", "setting_propagation"],
      "preconditions": ["caller must have tenant_admin role"],
      "postconditions": ["setting updated", "audit log entry created"]
    },
    {
      "intent": "admin.export_tenant_data",
      "entity": "tenant_data",
      "action_type": "read",
      "operation_id": "admin_export_tenant_data",
      "description": "Export all tenant data for compliance or migration purposes",
      "required_parameters": [
        {
          "name": "export_type",
          "type": "string",
          "enum": ["full", "users_only", "audit_logs", "gdpr_request"]
        }
      ],
      "optional_parameters": [
        {
          "name": "date_range",
          "type": "object",
          "properties": {
            "start": { "type": "string", "format": "date" },
            "end": { "type": "string", "format": "date" }
          }
        },
        { "name": "format", "type": "string", "enum": ["json", "csv", "zip"], "default": "zip" }
      ],
      "risk_level": "high",
      "confirmation_required": true,
      "async": true,
      "preconditions": [
        "caller must have tenant_admin role",
        "export must comply with data retention policy"
      ],
      "postconditions": ["export job created"]
    }
  ]
}
```

## Constraints & Safety Notes
- **Strict tenant boundary**: AXAG runtime MUST enforce that no operation accesses data outside the current tenant
- All operations require `tenant_admin` role
- Settings changes propagate to all tenant users and are logged to audit trail
- Data export is async and may take minutes for large tenants
- `gdpr_request` export type follows GDPR compliance requirements
- Tenant boundary violations MUST be treated as critical security incidents

## Cross-Domain Comparison

Source: https://axag.org/docs/use-cases/cross-domain-comparison

This page provides a comprehensive comparison of AXAG patterns across all domains, highlighting how the same core annotation model adapts to different business contexts.

## Risk Level Distribution by Domain

| Domain | None | Low | Medium | High | Critical |
|--------|------|-----|--------|------|----------|
| E-Commerce | Search, Track | Add to Cart | Checkout | Returns | — |
| Marketing | Segmentation | Campaign Create | — | Scheduling | — |
| CRM | Forecasting | Lead Create | Opportunity | — | — |
| Travel | Search | — | — | Cancellation | Booking |
| Jobs | Job Search | — | Application, Interview | — | — |
| Analytics | Dashboard, Export | Report Gen | — | — | — |
| Support | — | Ticket Create | Escalation | — | — |
| Enterprise | List Users | — | Submit Approval | Approve/Reject, Settings | Billing, MFA |

## Confirmation Requirements by Risk Level

| Risk Level | Confirmation Required? | Example |
|------------|----------------------|---------|
| `none` | No | Product search, dashboard filtering |
| `low` | No | Add to cart, create lead, create ticket |
| `medium` | Yes (recommended) | Begin checkout, submit application |
| `high` | **Yes (MUST)** | Returns, escalation, approve/reject |
| `critical` | **Yes (MUST)** + Approval | Travel booking, billing change, disable MFA |

## Idempotency Patterns

### Idempotent Operations (Safe to Retry)
- All `read` operations (search, list, track, filter, forecast)
- State transitions to same state (advance to same stage, approve already-approved)
- Schedule updates (re-scheduling to same time)
- Soft deletes (deleting already-deleted records)

### Non-Idempotent Operations (Dangerous to Retry)
- `create` operations (leads, tickets, campaigns, applications)
- Add to cart (doubles quantity)
- Report/export generation (creates duplicate jobs)
- Escalation (creates duplicate events)

## Common Annotation Attributes by Operation Type

### Read Operations
```
axag-action-type="read"
axag-risk-level="none"
axag-idempotent="true"
```

### Create Operations
```
axag-action-type="write"
axag-risk-level="low"
axag-idempotent="false"
```

### Update/State-Change Operations
```
axag-action-type="write"
axag-risk-level="medium" | "high"
axag-idempotent="true"
axag-confirmation-required="true" (if medium+)
```

### Delete/Destructive Operations
```
axag-action-type="delete"
axag-risk-level="high"
axag-confirmation-required="true"
axag-idempotent="true" (if soft delete)
```

### Financial/Critical Operations
```
axag-action-type="write"
axag-risk-level="critical"
axag-confirmation-required="true"
axag-approval-required="true"
axag-approval-roles='[...]'
```

## Scraping Failure Patterns

Every domain exhibits the same fundamental scraping failures:

| Failure Category | Examples |
|-----------------|----------|
| **Visual-only data** | Charts (Canvas/SVG), status icons, color-coded badges |
| **Dynamic components** | Date pickers, query builders, drag-and-drop, WYSIWYG editors |
| **Session/state dependency** | Cart state, auth tokens, tenant context, checkout sessions |
| **Anti-bot protection** | CAPTCHAs, rate limiting, fingerprinting, IP blocking |
| **External systems** | Payment iframes, calendar invites, carrier tracking, email delivery |
| **Build-tool obfuscation** | Hashed CSS classes, minified markup, tree-shaken components |

## AXAG Resolution Pattern

Across all domains, AXAG resolves these failures with the same three-layer approach:

```mermaid
graph LR
    A[Annotated UI] -->|generates| B[Semantic Manifest]
    B -->|generates| C[MCP Tool]
    C -->|consumed by| D[AI Agent]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#f3e5f5
```

1. **Annotation Layer**: `axag-*` attributes on HTML elements declare intent, parameters, constraints, and safety metadata
2. **Manifest Layer**: Machine-readable JSON manifest aggregates all annotations into a discoverable contract
3. **Tool Layer**: Generated MCP tools provide type-safe, constraint-aware callable interfaces for agents

This three-layer approach is **domain-agnostic** — the same annotation vocabulary works for e-commerce, CRM, analytics, and enterprise alike.

## Accessibility-Aligned Interaction Patterns

Source: https://axag.org/docs/use-cases/accessibility-patterns

AXAG and WCAG are complementary standards. WCAG makes interfaces accessible to humans with disabilities. AXAG makes interfaces accessible to AI agents. This page explains how they work together and demonstrates patterns that satisfy both.

## Problem Statement

Modern web applications must serve three audiences simultaneously:
1. **Sighted users** — who interact through visual UI
2. **Users with disabilities** — who rely on assistive technology (screen readers, keyboard navigation)
3. **AI agents** — who need machine-readable semantic contracts

Most teams treat these as separate concerns. This leads to:
- ARIA labels that describe visual appearance, not semantic intent
- Agent integrations built on fragile DOM scraping
- Accessibility and agent support drifting out of sync

## Why Human-Only Semantics Fail Agents

ARIA attributes describe **how** an element appears to assistive technology. AXAG describes **what** an element does semantically.

| ARIA | AXAG | Purpose |
|------|------|---------|
| `aria-label="Search products"` | `axag-intent="product.search"` | ARIA describes UI label; AXAG declares operation intent |
| `role="button"` | `axag-action-type="read"` | ARIA declares UI role; AXAG declares operation type |
| `aria-expanded="true"` | `axag-preconditions='["filter panel open"]'` | ARIA describes UI state; AXAG declares operational precondition |
| `aria-describedby="help-text"` | `axag-description="Search the product catalogue"` | ARIA links to UI text; AXAG provides machine-readable description |

An agent that reads ARIA labels can infer that a button is labeled "Search products" but cannot determine:
- What parameters the search accepts
- What entity is being searched
- What risk level applies
- Whether the operation is idempotent

## Combined ARIA + AXAG Pattern

```html title="Combined ARIA + AXAG — accessible to all audiences" showLineNumbers
<button
  role="button"
  aria-label="Search products"
  aria-describedby="search-help"
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category","price_min","price_max"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Search the product catalogue by keyword"
>
  🔍 Search
</button>
<span id="search-help" class="sr-only">Enter keywords to search products</span>
```

This element is accessible to:
- **Sighted users** — visible search button with icon
- **Screen readers** — `aria-label` provides spoken description
- **AI agents** — `axag-*` attributes provide full semantic contract

## Semantic Manifest Excerpt

```json title="Manifest excerpt"
{
  "intent": "product.search",
  "entity": "product",
  "action_type": "read",
  "operation_id": "product_search",
  "description": "Search the product catalogue by keyword",
  "required_parameters": [{ "name": "query", "type": "string" }],
  "optional_parameters": [
    { "name": "category", "type": "string" },
    { "name": "price_min", "type": "string" },
    { "name": "price_max", "type": "string" }
  ],
  "risk_level": "none",
  "idempotent": true
}
```

The manifest does not copy ARIA attributes. The accessible name stays in the markup, where screen readers and agents both read it.

## Generated MCP Tool

```json title="MCP tool — product_search"
{
  "name": "product_search",
  "description": "Search the product catalogue by keyword",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search keywords" },
      "category": { "type": "string" },
      "price_min": { "type": "number", "minimum": 0 },
      "price_max": { "type": "number", "minimum": 0 }
    },
    "required": ["query"]
  }
}
```

## Keyboard-Accessible Form with AXAG

```html title="Keyboard-accessible form with AXAG + ARIA" showLineNumbers
<form>
  <label for="ticket-subject">Subject</label>
  <input id="ticket-subject" name="subject" type="text" required
         aria-required="true" />

  <label for="ticket-description">Description</label>
  <textarea id="ticket-description" name="description" required
            aria-required="true"></textarea>

  <label for="ticket-priority">Priority</label>
  <select id="ticket-priority" name="priority" aria-label="Select priority">
    <option value="low">Low</option>
    <option value="medium">Medium</option>
    <option value="high">High</option>
  </select>

  <button type="submit"
    aria-label="Submit support ticket"
    axag-intent="ticket.create"
    axag-entity="ticket"
    axag-action-type="write"
    axag-required-parameters='["subject","description","priority"]'
    axag-risk-level="low"
    axag-idempotent="false"
    axag-side-effects='["ticket_created","support_team_notified"]'
    axag-description="Create a new support ticket"
  >Submit Ticket</button>
</form>
```

## Design Principles

1. **ARIA for humans, AXAG for agents** — never substitute one for the other
2. **Consistent labeling** — `aria-label` and `axag-description` should describe the same action, but from different perspectives
3. **Keyboard operability implies agent operability** — if an action is keyboard-accessible, it should also be AXAG-annotated
4. **Progressive enhancement** — add AXAG to existing accessible components without breaking ARIA

## Why Scraping Fails Here

Screen-reader-optimized sites often use:
- Visually hidden text (`sr-only` classes) that scrapers miss
- `aria-live` regions that change dynamically
- Focus management that scrapers cannot follow
- `role` attributes that describe UI patterns, not business operations

An agent scraping an accessible site might read `aria-label="Submit"` but cannot determine what entity is being submitted, what parameters are required, or whether the action needs confirmation.

## How AXAG Eliminates Scraping

With AXAG annotations alongside ARIA, the agent reads the semantic contract directly. It doesn't need to:
- Parse `aria-label` text for intent
- Traverse the DOM for form fields
- Infer parameters from `<input>` element names
- Guess risk level from button color or CSS class

## Next Steps

- [Failure Recovery and Retry Flows](/docs/use-cases/retry-and-recovery)
- [Enterprise Multi-Step Approval](/docs/use-cases/enterprise/multi-step-approval)
- [Annotating Forms](/docs/authoring-guide/annotating-forms)

## Failure Recovery and Retry Flows

Source: https://axag.org/docs/use-cases/retry-and-recovery

Agent-operated workflows will encounter failures — network timeouts, validation errors, rate limits, transient service outages. AXAG provides the semantic metadata agents need to decide whether to retry, how to recover, and when to escalate.

## Problem Statement

When an agent executes an operation and it fails, the agent needs to answer:

1. **Can I safely retry?** — Is the operation idempotent?
2. **What went wrong?** — Is this a transient error or a permanent failure?
3. **What are the preconditions?** — Do I need to re-establish state before retrying?
4. **Are there side effects?** — Has anything already happened that shouldn't repeat?
5. **Should I escalate?** — Is this a failure a human should handle?

Without AXAG, the agent has no structured way to answer these questions.

## Why Human-Only Semantics Fail Agents

When an operation fails in a human interface:
- A toast notification appears ("Something went wrong, try again")
- An error modal pops up with a generic message
- The page redirects to an error state

Agents cannot interpret these visual cues. They need machine-readable error semantics and retry guidance.

## AXAG Retry Metadata

### Idempotent Operations (Safe to Retry)

```html title="✅ Idempotent — safe to retry"
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-idempotent="true"
  axag-risk-level="none"
  axag-description="Search products — safe to retry on failure"
>Search</button>
```

When `axag-idempotent="true"`, the agent can safely retry without concern about duplicate side effects.

### Non-Idempotent Operations (Retry with Caution)

```html title="⚠️ Non-idempotent — do NOT retry blindly" showLineNumbers
<button
  axag-intent="order.place"
  axag-entity="order"
  axag-action-type="write"
  axag-idempotent="false"
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-side-effects='["payment_charged","inventory_deducted","confirmation_email_sent"]'
  axag-description="Place an order — do NOT retry blindly"
>Place Order</button>
```

When `axag-idempotent="false"` and side effects are declared, the agent knows:
- Retrying may cause duplicate charges
- It should check order status before retrying
- Escalation to a human may be safer than automatic retry

## Error Semantics

AXAG error codes provide structured failure information:

```json title="AXAG error response — structured failure info"
{
  "error": {
    "code": "AXAG-ERR-PRECONDITION",
    "message": "Precondition not met: cart must not be empty",
    "retryable": true,
    "recovery_action": "Ensure cart has items before placing order",
    "failed_precondition": "cart_not_empty"
  }
}
```

### Error Categories

| Error Code | Meaning | Retryable | Agent Action |
|-----------|---------|-----------|-------------|
| `AXAG-ERR-PRECONDITION` | Precondition not met | Yes (after fixing state) | Satisfy precondition, then retry |
| `AXAG-ERR-PARAMETER` | Invalid or missing parameter | Yes (with corrected params) | Fix parameters, then retry |
| `AXAG-ERR-UNAUTHORIZED` | Insufficient permissions | No | Escalate to human |
| `AXAG-ERR-RATE-LIMIT` | Rate limit exceeded | Yes (after delay) | Wait and retry with backoff |
| `AXAG-ERR-CONFLICT` | Concurrent modification | Yes (after refresh) | Refresh state, then retry |
| `AXAG-ERR-NOT-FOUND` | Entity does not exist | No | Report to user |
| `AXAG-ERR-SERVER` | Transient server error | Yes (with backoff) | Retry with exponential backoff |
| `AXAG-ERR-PERMANENT` | Permanent failure | No | Escalate to human |

## Recovery Flow Example

### Checkout with Automatic Recovery

```html title="3-step checkout with recovery annotations" showLineNumbers
<!-- Step 1: Validate Cart (idempotent, safe to retry) -->
<button
  axag-intent="cart.validate"
  axag-entity="cart"
  axag-action-type="read"
  axag-required-parameters='["cart_id"]'
  axag-idempotent="true"
  axag-postconditions='["cart_valid"]'
  axag-risk-level="none"
>Validate Cart</button>

<!-- Step 2: Reserve Inventory (idempotent with same cart_id) -->
<button
  axag-intent="inventory.reserve"
  axag-entity="inventory"
  axag-action-type="write"
  axag-required-parameters='["cart_id"]'
  axag-preconditions='["cart_valid"]'
  axag-postconditions='["inventory_reserved"]'
  axag-idempotent="true"
  axag-risk-level="low"
  axag-side-effects='["inventory_hold_created"]'
>Reserve Inventory</button>

<!-- Step 3: Process Payment (NOT idempotent) -->
<button
  axag-intent="payment.charge"
  axag-entity="payment"
  axag-action-type="write"
  axag-required-parameters='["cart_id","payment_method_id","amount"]'
  axag-preconditions='["inventory_reserved","payment_method_valid"]'
  axag-postconditions='["payment_processed"]'
  axag-idempotent="false"
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-side-effects='["payment_charged"]'
>Process Payment</button>
```

**Agent recovery logic:**
1. If Step 1 fails → retry immediately (idempotent read)
2. If Step 2 fails → retry (idempotent with same cart_id)
3. If Step 3 fails → **do NOT retry** — check payment status first, then decide

## Semantic Manifest with Retry Metadata

```json title="Manifest — payment.charge with retry metadata" showLineNumbers
{
  "intent": "payment.charge",
  "entity": "payment",
  "action_type": "write",
  "idempotent": false,
  "risk_level": "high",
  "side_effects": ["payment_charged"],
  "error_handling": {
    "retryable_errors": ["AXAG-ERR-RATE-LIMIT", "AXAG-ERR-SERVER"],
    "non_retryable_errors": ["AXAG-ERR-PARAMETER", "AXAG-ERR-UNAUTHORIZED"],
    "max_retries": 0,
    "recovery_hint": "Check payment status before retrying"
  }
}
```

## Generated MCP Tool

```json title="Tool — payment_charge (no auto-retry)" showLineNumbers
{
  "name": "payment_charge",
  "description": "Process payment — NOT idempotent, do not retry without checking status",
  "inputSchema": {
    "type": "object",
    "properties": {
      "cart_id": { "type": "string" },
      "payment_method_id": { "type": "string" },
      "amount": { "type": "number", "minimum": 0.01 }
    },
    "required": ["cart_id", "payment_method_id", "amount"]
  },
  "safety": {
    "risk_level": "high",
    "idempotent": false,
    "confirmation_required": true,
    "side_effects": ["payment_charged"],
    "retry_policy": "no_auto_retry"
  }
}
```

## Why Scraping Fails Here

When an agent scrapes a checkout page and encounters an error:
- It sees a toast saying "Payment failed, please try again"
- It cannot determine if the payment was partially processed
- It cannot tell if retrying will cause a double charge
- It has no structured error code to interpret

## How AXAG Eliminates Scraping

With AXAG:
- `axag-idempotent="false"` tells the agent: **do not retry blindly**
- `axag-side-effects='["payment_charged"]'` warns of irreversible consequences
- Structured error codes provide machine-readable failure categories
- Recovery hints guide the agent to safe next steps

## Next Steps

- [Accessibility-Aligned Patterns](/docs/use-cases/accessibility-patterns)
- [Error Semantics](/docs/specification/error-semantics)
- [Error Codes Reference](/docs/reference/error-codes)


# Validation

## Static Validation

Source: https://axag.org/docs/validation/static-validation

Static validation checks AXAG annotations at build time — before the page is served. This catches errors early, prevents invalid annotations from reaching production, and integrates with CI/CD pipelines.

## What Static Validation Checks

### Structural Validation
- All `axag-intent` values follow the `entity.action` naming convention
- Required attributes (`axag-intent`, `axag-entity`, `axag-action-type`) are present
- JSON attribute values (`axag-required-parameters`, `axag-optional-parameters`) are valid JSON
- Enum values for `axag-action-type`, `axag-risk-level` are from the allowed set

### Semantic Validation
- `axag-required-parameters` and `axag-optional-parameters` don't overlap
- `axag-confirmation-required="true"` is set when `axag-risk-level` is `high` or `critical`
- `axag-approval-required="true"` has a corresponding `axag-approval-roles`
- `axag-idempotent` is declared for all write/delete operations
- `axag-scope` is declared for tenant-sensitive operations

### Cross-Reference Validation
- All intents referenced in annotations exist in the Semantic Manifest
- Parameter names in annotations match the manifest parameter definitions
- Entity names are consistent between annotations and manifest

## Validation Tool Example

```bash title="Static validation output"
# Run static validation
npx axag-lint src --manifest axag-manifest.json

# Output
✓ 47 annotations found
✓ All structural checks passed
✓ All semantic checks passed
✗ 2 cross-reference warnings:
  - src/components/Cart.tsx:42 — intent "cart.remove_item" not in manifest
  - src/pages/Admin.tsx:108 — parameter "user_role" not declared in manifest
```

## Integration with Build Tools

`@axag/compiler` reads annotations during the build and fails it on error diagnostics, so a broken annotation never reaches a deploy. See [Build-Time Compilation](/docs/tool-generation/build-time-compilation).

### Vite
```typescript title="vite.config.ts"

  plugins: [axag({ failOnError: true })],
});
```

### webpack
```javascript title="webpack.config.js"
const axag = require('@axag/compiler/webpack').default;

module.exports = {
  plugins: [axag({ failOnError: true })],
};
```

Rollup, Rspack and esbuild import from `@axag/compiler/rollup`, `/rspack` and `/esbuild`.

## Lint Rules

`axag-lint` ships 35 rules, grouped by what they protect:

| Rules | Cover |
|-------|-------|
| 001–003, 034–035 | Identity: intent, entity and action type present and correctly shaped |
| 004–005 | Enum values |
| 006–007, 023–026 | Safety: risk, confirmation, approval, idempotency |
| 008–009 | Parameters |
| 010 | Cross-reference against a generated manifest |
| 011, 018–022 | Scope and tenancy |
| 012–016 | Contradictions between attributes |
| 017 | Unsafe mutations |
| 027–028 | Macro syntax and macro/longhand conflicts |
| 029–032 | Harvesting: unnamed controls, schema drift, accessible names, labels |
| 033 | Annotations that exist only at runtime |

Each has a default severity you can change per project. See [CI/CD Linting](/docs/validation/ci-linting) for the configuration file, and the [axag-lint README](https://www.npmjs.com/package/@web-axag/axag-lint) for the full list.

## Project-Specific Severities

Rules are turned up, down or off per project rather than rewritten:

```json title=".axaglintrc.json"
{
  "rules": {
    "AXAG-LINT-024": "error",
    "AXAG-LINT-025": "off"
  }
}
```

Domain rules of your own — "every billing action must be high risk or above" — aren't part of the linter yet; today that check belongs in a CI script over the generated manifest, which is JSON:

```bash title="A domain rule over the manifest"
npx axag generate src --manifest axag-manifest.json
node -e "const m=require('./axag-manifest.json');\
  const bad=m.actions.filter(a=>['billing','payment','refund'].includes(a.entity) && !['high','critical'].includes(a.risk_level));\
  if (bad.length) { console.error('Financial actions below high risk:', bad.map(a=>a.intent)); process.exit(1); }"
```

## Runtime Validation

Source: https://axag.org/docs/validation/runtime-validation

Runtime validation ensures AXAG contracts are honored during agent execution. While static validation catches structural errors, runtime validation catches behavioral violations — an agent attempting an action without meeting preconditions, exceeding parameter constraints, or violating safety boundaries.

## Runtime Validation Points

### Pre-Execution Validation
Before executing a tool call, the runtime validates:
- **Required parameters**: All required parameters are present and non-null
- **Type constraints**: Parameter values match declared types
- **Range constraints**: Numeric values are within `minimum`/`maximum` bounds
- **Enum constraints**: String values are from declared enum sets
- **Format constraints**: Values match declared formats (email, date, URI)
- **Preconditions**: Declared preconditions are checked (where machine-checkable)

### Execution-Time Validation
During execution, the runtime enforces:
- **Confirmation gate**: If `confirmation_required=true`, ensure user confirmation was obtained
- **Approval gate**: If `approval_required=true`, verify approval token from authorized role
- **Scope boundary**: Ensure the operation stays within declared scope (tenant, user, etc.)
- **Idempotency check**: For non-idempotent operations, warn if duplicate detected

### Post-Execution Validation
After execution, the runtime verifies:
- **Postconditions**: Declared postconditions are met (where verifiable)
- **Side-effects**: Declared side-effects occurred as expected
- **Error semantics**: Error responses follow the declared error schema

## Implementation Pattern

```typescript title="AXAGRuntimeValidator — interface" showLineNumbers
interface AXAGRuntimeValidator {
  validatePreExecution(
    toolCall: ToolCall,
    manifest: ManifestAction
  ): ValidationResult;

  validateConfirmation(
    toolCall: ToolCall,
    confirmationToken: string | null
  ): ValidationResult;

  validateApproval(
    toolCall: ToolCall,
    approvalToken: string | null,
    approverRole: string
  ): ValidationResult;

  validatePostExecution(
    toolCall: ToolCall,
    result: ExecutionResult,
    manifest: ManifestAction
  ): ValidationResult;
}

interface ValidationResult {
  valid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
}
```

## Error Response Format

When runtime validation fails, the error response follows a standard format:

```json title="Validation error response"
{
  "error": {
    "code": "AXAG_VALIDATION_ERROR",
    "type": "precondition_failed",
    "message": "Precondition not met: cart must have at least one item",
    "details": {
      "intent": "cart.begin_checkout",
      "failed_precondition": "cart must have at least one item",
      "suggestion": "Add items to cart before beginning checkout"
    }
  }
}
```

## Common Runtime Validation Errors

| Error Code | Type | Description |
|-----------|------|-------------|
| `AXAG_MISSING_PARAM` | `parameter_error` | Required parameter not provided |
| `AXAG_INVALID_TYPE` | `parameter_error` | Parameter value has wrong type |
| `AXAG_OUT_OF_RANGE` | `constraint_error` | Numeric value outside min/max |
| `AXAG_INVALID_ENUM` | `constraint_error` | Value not in allowed enum set |
| `AXAG_PRECONDITION_FAILED` | `precondition_error` | Precondition check failed |
| `AXAG_CONFIRMATION_MISSING` | `safety_error` | Confirmation required but not provided |
| `AXAG_APPROVAL_MISSING` | `safety_error` | Approval required but not provided |
| `AXAG_SCOPE_VIOLATION` | `security_error` | Operation outside declared scope |
| `AXAG_TENANT_BOUNDARY` | `security_error` | Cross-tenant access attempt |
| `AXAG_ROLE_INSUFFICIENT` | `authorization_error` | Caller lacks required role |

## CI/CD Linting

Source: https://axag.org/docs/validation/ci-linting

Integrating AXAG validation into your CI/CD pipeline ensures that annotation errors are caught before deployment. This page shows how to set up automated linting with GitHub Actions, GitLab CI, and other platforms.

## GitHub Actions Workflow

```yaml title=".github/workflows/axag-validation.yml" showLineNumbers
name: AXAG Validation

on:
  pull_request:
    paths:
      - 'src/**'
      - 'axag-manifest.json'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Generate and validate the manifest
        run: npx axag generate src --manifest axag-manifest.json --validate

      - name: Run AXAG lint rules
        run: npx axag-lint src --manifest axag-manifest.json --format github

      - name: Check conformance level
        run: npx axag validate src --level intermediate --strict
```

## GitLab CI Configuration

```yaml title=".gitlab-ci.yml"
axag-validate:
  stage: test
  image: node:20
  script:
    - npm ci
    - npx axag generate src --manifest axag-manifest.json --validate
    - npx axag-lint src --manifest axag-manifest.json --format json
  rules:
    - changes:
        - src/**
        - axag-manifest.json
```

## Lint Configuration File

Create `.axaglintrc.json` in your project root, or put the same object under an `"axag-lint"` key in `package.json`. Anything you leave out keeps its default.

```json title=".axaglintrc.json" showLineNumbers
{
  "include": ["**/*.{html,htm,jsx,tsx,vue}"],
  "exclude": ["node_modules/**", "dist/**", "build/**", "**/*.test.*"],
  "manifestPath": "./axag-manifest.json",
  "rules": {
    "AXAG-LINT-025": "off",
    "AXAG-LINT-031": "warning",
    "AXAG-LINT-032": "off"
  }
}
```

Each rule takes `"error"`, `"warning"`, `"info"` or `"off"`. Run `npx axag-lint --init` to write the file with every rule at its default severity.

### What the rules cover

| Rules | Cover |
|-------|-------|
| 001–003, 034–035 | Identity: intent, entity and action type present and correctly shaped |
| 004–005 | Enum values |
| 006–007, 023–026 | Safety: risk, confirmation, approval, idempotency |
| 008–009 | Parameters |
| 010 | Cross-reference against the manifest (needs `manifestPath`) |
| 011, 018–022 | Scope and tenancy |
| 012–016 | Contradictions between attributes |
| 017 | Unsafe mutations |
| 027–028 | Macro syntax and macro/longhand conflicts |
| 029–032 | Harvesting: unnamed controls, schema drift, accessible names, labels |
| 033 | Annotations that only exist at runtime |

The full list with default severities is in the [axag-lint README](https://www.npmjs.com/package/@web-axag/axag-lint).

## Pre-Commit Hook

Use Husky to validate annotations before commit:

```bash title=".husky/pre-commit"
# .husky/pre-commit — lint the files about to be committed
git diff --cached --name-only --diff-filter=ACM \
  | grep -E '\.(html|htm|jsx|tsx|vue)$' \
  | xargs -r npx axag-lint
```

## CI Output Formats

The `--format` flag controls output format:

| Format | Use Case |
|--------|----------|
| `console` | Local terminal output (default) |
| `github` | Annotations shown inline on the pull request |
| `sarif` | GitHub code scanning — the Security tab |
| `json` | Machine-readable for custom tooling |

`--output <path>` writes the report to a file, `--quiet` shows errors only, and `--manifest <path>` turns on the rules that compare annotations with a generated manifest.

## The action

```yaml title=".github/workflows/axag.yml"
name: AXAG

on: pull_request

permissions:
  contents: read
  security-events: write

jobs:
  axag:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }

      - name: Generate the manifest
        run: npx --yes @web-axag/axag-cli generate src --manifest axag-manifest.json --validate

      - uses: axag-sdk/axag-sdk/.github/actions/axag-lint@main
        with:
          path: src
          manifest: axag-manifest.json
          changed-since: origin/${{ github.base_ref }}

      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: axag-lint.sarif
```

## Turning it on in an existing codebase

Rules like AXAG-LINT-031 (no accessible name) can fire hundreds of times on a codebase that predates them. A baseline records what is already there, so only new findings fail:

```bash
npx axag-lint src --update-baseline   # writes .axag-lint-baseline.json
npx axag-lint src --baseline          # from now on, only new findings
```

The baseline records rule and file, not line numbers, so unrelated edits don't reset it — and a *new* finding of the same kind in the same file still reports.

`--changed-since origin/main` narrows a run to the files a pull request touched, which pairs well with a baseline while a team works through the backlog.

## Enforcing Conformance Levels in CI

```bash
# Fail on annotations below a level (basic | intermediate | full)
npx axag validate src --level intermediate --strict
```

`axag validate` runs the same rules as `axag-lint`, limited to the categories that level asks for: identity, enums, parameters and macro syntax at `basic`; safety, scope and harvesting at `intermediate`; contradictions, manifest cross-references and enforcement at `full`.

`axag validate` exits with code 1 when an annotation misses what the level requires, blocking the pipeline. The manifest also records the level it reached in its `conformance` field, so `axag generate --validate` shows where a codebase stands without failing the build.

## Schema Conformance

Source: https://axag.org/docs/validation/schema-conformance

Schema conformance verifies that AXAG annotations and manifests comply with the formal AXAG schema definition. This ensures interoperability across tools, runtimes, and agent frameworks.

## AXAG JSON Schema

The canonical AXAG manifest schema is a JSON Schema document:

```json title="AXAG Manifest JSON Schema" showLineNumbers
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://axag.org/schema/manifest/1.0.0",
  "title": "AXAG Semantic Manifest",
  "type": "object",
  "required": ["version", "entities"],
  "properties": {
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$"
    },
    "entities": {
      "type": "array",
      "items": { "$ref": "#/$defs/Entity" }
    },
    "metadata": { "$ref": "#/$defs/Metadata" }
  },
  "$defs": {
    "Entity": {
      "type": "object",
      "required": ["name", "actions"],
      "properties": {
        "name": { "type": "string", "pattern": "^[a-z_]+$" },
        "description": { "type": "string" },
        "actions": {
          "type": "array",
          "items": { "$ref": "#/$defs/Action" }
        }
      }
    },
    "Action": {
      "type": "object",
      "required": ["intent", "action_type"],
      "properties": {
        "intent": { "type": "string", "pattern": "^[a-z_]+\\.[a-z_]+$" },
        "action_type": { "enum": ["read", "write", "delete"] },
        "risk_level": { "enum": ["none", "low", "medium", "high", "critical"] },
        "idempotent": { "type": "boolean" },
        "confirmation_required": { "type": "boolean" },
        "approval_required": { "type": "boolean" },
        "parameters": { "$ref": "#/$defs/Parameters" }
      }
    },
    "Parameters": {
      "type": "object",
      "additionalProperties": { "$ref": "#/$defs/ParameterDef" }
    },
    "ParameterDef": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": { "type": "string" },
        "required": { "type": "boolean" },
        "enum": { "type": "array" },
        "minimum": { "type": "number" },
        "maximum": { "type": "number" },
        "maxLength": { "type": "integer" },
        "format": { "type": "string" },
        "default": {}
      }
    },
    "Metadata": {
      "type": "object",
      "properties": {
        "generator": { "type": "string" },
        "generated_at": { "type": "string", "format": "date-time" },
        "source_url": { "type": "string", "format": "uri" }
      }
    }
  }
}
```

## Conformance Levels

### Level 1: Basic
All required fields present. Intent, entity, and action_type declared for every annotation.

### Level 2: Intermediate
Basic + parameters declared with types, risk levels assigned, idempotency declared, scope declared.

### Level 3: Full
Intermediate + preconditions/postconditions, side-effects, approval roles, error semantics, tenant boundaries.

## Validation Commands

```bash
# Generate the manifest and validate it against the schema in one step
npx axag generate src --manifest axag-manifest.json --validate

# Validate a manifest you already have, against a published schema version
curl -sO https://axag.org/schema/v1.1/axag-manifest.schema.json
npx ajv-cli validate -s axag-manifest.schema.json -d axag-manifest.json

# Check annotations against a conformance level
npx axag validate src --level full --strict
```

A manifest also reports the level it reached in its own `conformance` field, computed from what its actions declare.

## Schema Evolution

The AXAG schema follows semantic versioning:
- **Patch** (0.1.x): Bug fixes in schema definitions
- **Minor** (0.x.0): New optional fields added (backward-compatible)
- **Major** (x.0.0): Breaking changes to required fields or structure

## Contradictory Annotation Detection

Source: https://axag.org/docs/validation/contradictory-annotation-detection

Contradictory annotations occur when two or more AXAG attributes on the same element express incompatible semantics. These contradictions create ambiguity for agents, which cannot determine the correct interpretation.

## Why It Matters

When an agent encounters contradictory annotations, it must either:
- Guess which attribute to trust (dangerous)
- Reject the operation entirely (safe but limits functionality)
- Ask for human clarification (possible but defeats automation)

None of these outcomes are acceptable in production. **Contradictions MUST be detected and resolved before deployment.**

## Common Contradictions

### 1. Risk Level vs Action Type

A `read` operation annotated with `high` risk:

```html title="❌ Contradictory — read with high risk"
<!-- ❌ Contradictory: reads are inherently safe -->
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-risk-level="high"
>Search</button>
```

**Rule:** `AXAG-LINT-010` — Read operations **SHOULD NOT** have risk level above `low`.

**Fix:**
```html title="✅ Fix — risk level matches action type"
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-risk-level="none"
>Search</button>
```

### 2. Idempotent vs Side Effects

An operation declared idempotent but with non-idempotent side effects:

```html title="❌ Contradictory — idempotent with non-idempotent side effects"
<!-- ❌ Contradictory: email_sent is not idempotent -->
<button
  axag-intent="order.place"
  axag-entity="order"
  axag-action-type="write"
  axag-idempotent="true"
  axag-side-effects='["email_sent","inventory_deducted"]'
  axag-risk-level="high"
>Place Order</button>
```

**Rule:** `AXAG-LINT-011` — Idempotent operations **MUST NOT** declare non-idempotent side effects.

**Fix:** Either mark as non-idempotent or ensure side effects are truly idempotent (e.g., "email_sent" becomes "email_queued_idempotent").

### 3. Confirmation Not Required on Destructive Actions

```html title="❌ Contradictory — delete without confirmation"
<!-- ❌ Contradictory: delete without confirmation -->
<button
  axag-intent="user.delete"
  axag-entity="user"
  axag-action-type="delete"
  axag-risk-level="critical"
  axag-confirmation-required="false"
>Delete User</button>
```

**Rule:** `AXAG-LINT-012` — Delete operations with risk level `high` or `critical` **MUST** require confirmation.

### 4. Approval Without Roles

```html
<!-- ❌ Contradictory: approval required but no roles specified -->
<button
  axag-intent="expense.approve"
  axag-entity="expense"
  axag-action-type="write"
  axag-approval-required="true"
  axag-risk-level="high"
>Approve</button>
```

**Rule:** `AXAG-LINT-013` — When `axag-approval-required="true"`, `axag-approval-roles` **MUST** be specified.

### 5. Preconditions Contradicting Action Type

```html
<!-- ❌ Contradictory: create with "entity must exist" precondition -->
<button
  axag-intent="product.create"
  axag-entity="product"
  axag-action-type="write"
  axag-preconditions='["product must exist"]'
>Create Product</button>
```

**Rule:** `AXAG-LINT-014` — Create operations **SHOULD NOT** require the target entity to already exist.

## Detection Rules Summary

| Rule | Contradiction | Severity |
|------|--------------|----------|
| `AXAG-LINT-010` | Read + high/critical risk | Warning |
| `AXAG-LINT-011` | Idempotent + non-idempotent side effects | Error |
| `AXAG-LINT-012` | Destructive + no confirmation (high/critical) | Error |
| `AXAG-LINT-013` | Approval required + no approval roles | Error |
| `AXAG-LINT-014` | Create + "must exist" precondition | Warning |
| `AXAG-LINT-015` | Navigate + side effects declared | Warning |
| `AXAG-LINT-016` | Non-tenant scope + tenant-only roles | Error |

## CI Integration

```yaml
# In your CI pipeline
- name: Check for contradictory annotations
  run: npx axag-lint src --format github
```

## Next Steps

- [Missing Intent Detection](/docs/validation/missing-intent-detection)
- [Unsafe Mutation Exposure Detection](/docs/validation/unsafe-mutation-detection)
- [Common Validation Failures](/docs/validation/common-failures)

## Missing Intent Detection

Source: https://axag.org/docs/validation/missing-intent-detection

Missing intent detection identifies interactive UI elements that lack AXAG annotations — elements an agent cannot interpret semantically.

## Why It Matters

Every unannotated interactive element is a gap in the semantic contract. When an agent encounters a button, link, or form without `axag-intent`, it must fall back to:

- DOM scraping (brittle)
- Label inference (ambiguous)
- Visual layout parsing (fragile)

These are exactly the failure modes AXAG is designed to eliminate.

## What Counts as "Missing Intent"

An element has a missing intent if it:

1. Is an interactive HTML element (`<button>`, `<a>`, `<input type="submit">`, `<form>`)
2. Has a click handler, form action, or navigation target
3. Does **not** have an `axag-intent` attribute

### Elements That MUST Be Annotated

| Element | Condition | Required |
|---------|-----------|----------|
| `<button>` | Always | Yes |
| `<a>` with `href` | When performing an action (not just navigation) | Recommended |
| `<input type="submit">` | Always | Yes |
| `<form>` submit buttons | Always | Yes |
| Elements with `onclick` | Always | Yes |
| Elements with `role="button"` | Always | Yes |

### Elements That MAY Be Skipped

- Pure navigational links (`<a href="/about">`)
- Decorative elements
- Elements inside annotated parents (if context inheritance applies)

## Detection Rules

### AXAG-LINT-001: Missing Intent

```
Rule: AXAG-LINT-001
Severity: Error
Message: Interactive element missing axag-intent attribute
Fix: Add axag-intent with the semantic operation identifier
```

**Failing example:**
```html title="❌ No intent declared"
<!-- ❌ No intent declared -->
<button onclick="submitOrder()">Place Order</button>
```

**Passing example:**
```html title="✅ Intent declared"
<!-- ✅ Intent declared -->
<button
  onclick="submitOrder()"
  axag-intent="order.place"
  axag-entity="order"
  axag-action-type="write"
>Place Order</button>
```

### AXAG-LINT-001a: Missing Entity

```
Rule: AXAG-LINT-001a
Severity: Error
Message: Element has axag-intent but missing axag-entity
Fix: Add axag-entity with the domain object name
```

### AXAG-LINT-001b: Missing Action Type

```
Rule: AXAG-LINT-001b
Severity: Error
Message: Element has axag-intent but missing axag-action-type
Fix: Add axag-action-type with read, write, delete, or navigate
```

## Coverage Metrics

Track annotation coverage as a quality metric:

```
Annotation Coverage = (annotated interactive elements / total interactive elements) × 100
```

| Coverage Level | Percentage | Assessment |
|---------------|-----------|------------|
| None | 0% | No semantic contract |
| Minimal | 1–25% | Early adoption |
| Partial | 26–50% | In progress |
| Substantial | 51–75% | Good coverage |
| Comprehensive | 76–99% | Production-ready |
| Complete | 100% | Full semantic contract |

## Scanning Approach

A missing-intent scanner should:

1. Parse the HTML/JSX/TSX file
2. Identify all interactive elements
3. Check each for `axag-intent`
4. Report unannotated elements with file path and line number
5. Exclude elements marked with `axag-skip="true"` (opt-out)

### Opt-Out Mechanism

For elements that intentionally lack annotations (e.g., purely decorative interactions):

```html
<!-- Explicitly excluded from annotation requirements -->
<button axag-skip="true" onclick="toggleTheme()">🌙</button>
```

## CI Integration

```yaml
- name: Check for missing intents
  run: npx axag-lint src --format github
```

The `--threshold` flag sets the minimum annotation coverage percentage. The build fails if coverage drops below this threshold.

## Next Steps

- [Unsafe Mutation Exposure Detection](/docs/validation/unsafe-mutation-detection)
- [Scope Mismatch Detection](/docs/validation/scope-mismatch-detection)
- [Remediation Guidance](/docs/validation/remediation-guidance)

## Unsafe Mutation Exposure Detection

Source: https://axag.org/docs/validation/unsafe-mutation-detection

Unsafe mutation exposure occurs when a write, delete, or mutate operation is annotated without adequate safety metadata — exposing the operation to unchecked agent execution.

## Why It Matters

When an agent discovers a mutation operation without safety constraints, it may:

- Execute destructive actions without confirmation
- Trigger financial transactions without approval
- Modify shared state without tenant boundaries
- Invoke non-idempotent operations multiple times

These scenarios represent **real production risk**.

## What Constitutes "Unsafe Exposure"

A mutation is considered unsafely exposed when any of these conditions are true:

| Condition | Risk |
|-----------|------|
| `action-type` is `write` or `delete` but no `risk-level` | Agent cannot assess risk |
| `risk-level` is `high` or `critical` but `confirmation-required` is `false` or missing | Dangerous action without human check |
| `action-type` is `delete` but no `preconditions` | No guard against invalid deletion |
| `action-type` is `write` with financial side effects but no `approval-required` | Financial risk without governance |
| `idempotent` is `false` or missing with no `side-effects` declaration | Agent cannot predict consequences |
| `scope` is missing on tenant-sensitive mutations | Cross-tenant data corruption risk |

## Detection Rules

### AXAG-LINT-003: Unsafe Mutate Without Confirmation

```
Rule: AXAG-LINT-003
Severity: Error
Message: Mutation operation with risk-level high/critical lacks confirmation requirement
Fix: Add axag-confirmation-required="true"
```

**Failing example:**
```html title="❌ Unsafe — no confirmation on critical delete"
<button
  axag-intent="account.delete"
  axag-entity="account"
  axag-action-type="delete"
  axag-risk-level="critical"
>Delete Account</button>
```

**Passing example:**
```html title="✅ Safe — full safety metadata" showLineNumbers
<button
  axag-intent="account.delete"
  axag-entity="account"
  axag-action-type="delete"
  axag-risk-level="critical"
  axag-confirmation-required="true"
  axag-preconditions='["no active subscriptions"]'
  axag-postconditions='["account deactivated","data retention started"]'
  axag-idempotent="true"
>Delete Account</button>
```

### AXAG-LINT-008: Delete Without Preconditions

```
Rule: AXAG-LINT-008
Severity: Warning
Message: Delete operation has no preconditions declared
Fix: Add axag-preconditions with state requirements
```

### AXAG-LINT-009: Financial Mutation Without Approval

```
Rule: AXAG-LINT-009
Severity: Error
Message: Mutation with financial side effects lacks approval requirement
Fix: Add axag-approval-required="true" and axag-approval-roles
```

**Example — financial mutation:**
```html
<button
  axag-intent="refund.process"
  axag-entity="refund"
  axag-action-type="write"
  axag-required-parameters='["order_id","amount"]'
  axag-risk-level="high"
  axag-side-effects='["payment_refund","accounting_adjustment"]'
  axag-confirmation-required="true"
  axag-approval-required="true"
  axag-approval-roles='["finance_manager"]'
  axag-scope="tenant"
  axag-idempotent="true"
>Process Refund</button>
```

### AXAG-LINT-017: Missing Side Effects Declaration

```
Rule: AXAG-LINT-017
Severity: Warning
Message: Non-idempotent mutation has no side-effects declared
Fix: Add axag-side-effects listing observable state changes
```

## Risk-Level Enforcement Matrix

| Action Type | Minimum Required Safety Metadata |
|------------|----------------------------------|
| `read` | None (risk should be `none` or `low`) |
| `write` (low risk) | `risk-level` |
| `write` (medium risk) | `risk-level`, `confirmation-required` |
| `write` (high risk) | `risk-level`, `confirmation-required`, `preconditions` |
| `delete` | `risk-level`, `confirmation-required`, `preconditions` |
| `delete` (critical) | All of above + `approval-required`, `approval-roles` |

## CI Integration

```yaml
- name: Check for unsafe mutations
  run: npx axag-lint src --format github
```

## Next Steps

- [Scope Mismatch Detection](/docs/validation/scope-mismatch-detection)
- [Risk-Level Validation](/docs/validation/risk-level-validation)
- [Remediation Guidance](/docs/validation/remediation-guidance)

## Scope Mismatch Detection

Source: https://axag.org/docs/validation/scope-mismatch-detection

Scope mismatch detection identifies annotations where the declared `axag-scope` is inconsistent with the operation's actual access pattern, tenant model, or role requirements.

## Why It Matters

Scope mismatches can cause:

- **Cross-tenant data leakage** — An operation scoped to `global` that should be scoped to `tenant`
- **Privilege escalation** — An operation scoped to `user` that actually modifies tenant-wide settings
- **Broken authorization** — Roles defined for one scope applied in another
- **Agent over-reach** — An agent invoking operations beyond its authorized boundary

## Common Scope Mismatches

### 1. Missing Scope on Tenant-Sensitive Operations

```html title="❌ No scope — agent can't determine tenant boundary"
<!-- ❌ No scope declared — agent doesn't know tenant boundary -->
<button
  axag-intent="user.list"
  axag-entity="user"
  axag-action-type="read"
  axag-required-roles='["admin"]'
>List All Users</button>
```

**Rule:** `AXAG-LINT-004` — Operations with role requirements **MUST** declare a scope.

**Fix:**
```html title="✅ Fix — add tenant scope"
<button
  axag-intent="user.list"
  axag-entity="user"
  axag-action-type="read"
  axag-required-roles='["admin"]'
  axag-scope="tenant"
>List All Users</button>
```

### 2. Global Scope on User-Specific Operations

```html title="❌ Global scope on personal action"
<!-- ❌ Global scope on a personal action -->
<button
  axag-intent="profile.update"
  axag-entity="profile"
  axag-action-type="write"
  axag-scope="global"
  axag-required-parameters='["user_id","display_name"]'
>Update Profile</button>
```

**Rule:** `AXAG-LINT-018` — Operations on personal entities **SHOULD** use `user` scope, not `global`.

**Fix:**
```html title="✅ Fix — use user scope"
<button
  axag-intent="profile.update"
  axag-entity="profile"
  axag-action-type="write"
  axag-scope="user"
  axag-required-parameters='["display_name"]'
>Update Profile</button>
```

### 3. Tenant Scope Without Tenant-Aware Roles

```html
<!-- ❌ Tenant scope but roles don't include tenant context -->
<button
  axag-intent="settings.update"
  axag-entity="settings"
  axag-action-type="write"
  axag-scope="tenant"
  axag-required-roles='["superadmin"]'
>Update Settings</button>
```

**Rule:** `AXAG-LINT-019` — `superadmin` roles typically imply `global` scope. Verify if `tenant` is correct.

### 4. Cross-Entity Scope Inconsistency

When two operations on the same page operate on the same entity but declare different scopes:

```html
<!-- Operation 1: tenant scope -->
<button axag-intent="report.generate" axag-entity="report"
  axag-action-type="read" axag-scope="tenant">Generate</button>

<!-- Operation 2: global scope (on same entity) -->
<button axag-intent="report.delete" axag-entity="report"
  axag-action-type="delete" axag-scope="global">Delete</button>
```

**Rule:** `AXAG-LINT-020` — Operations on the same entity within a page **SHOULD** use consistent scope unless justified.

## Scope Hierarchy

```
global
  └── tenant
       └── team
            └── user
```

| Scope | Meaning | Typical Operations |
|-------|---------|-------------------|
| `global` | Platform-wide, all tenants | System settings, platform analytics |
| `tenant` | Within a single tenant/organization | Team management, tenant config, business data |
| `team` | Within a team or department | Team-specific dashboards, shared resources |
| `user` | Personal to the current user | Profile, preferences, personal data |

## Detection Rules Summary

| Rule | Mismatch | Severity |
|------|----------|----------|
| `AXAG-LINT-004` | Role requirements without scope | Error |
| `AXAG-LINT-018` | Global scope on personal operations | Warning |
| `AXAG-LINT-019` | Scope/role hierarchy mismatch | Warning |
| `AXAG-LINT-020` | Inconsistent scope on same entity | Warning |
| `AXAG-LINT-021` | Delete operation without scope | Error |
| `AXAG-LINT-022` | Tenant mutation with user scope | Error |

## CI Integration

```yaml
- name: Check for scope mismatches
  run: npx axag-lint src --format github
```

## Next Steps

- [Risk-Level Validation](/docs/validation/risk-level-validation)
- [Common Validation Failures](/docs/validation/common-failures)
- [Remediation Guidance](/docs/validation/remediation-guidance)

## Risk-Level Validation

Source: https://axag.org/docs/validation/risk-level-validation

Risk-level validation ensures that the `axag-risk-level` attribute accurately reflects the operation's actual danger and that corresponding safety metadata is proportional.

## Why It Matters

Incorrect risk levels undermine the entire safety model:

- **Under-classified risk** — Dangerous operations executed without safeguards
- **Over-classified risk** — Benign operations blocked by unnecessary friction
- **Missing risk metadata** — Agents cannot make informed execution decisions

## Risk-Level Definitions

| Level | Operations | Expected Safeguards |
|-------|-----------|-------------------|
| `none` | Read-only queries, searches, listings | None required |
| `low` | Creating non-critical records, bookmarks | Logging |
| `medium` | Updating records, status changes | Confirmation |
| `high` | Financial transactions, bulk operations, deletions | Confirmation + preconditions |
| `critical` | Permanent deletions, admin operations, compliance actions | Confirmation + approval + preconditions |

## Validation Rules

### AXAG-LINT-023: Missing Risk Level on Mutations

```
Rule: AXAG-LINT-023
Severity: Error
Message: Write or delete operation has no risk-level declared
Fix: Add axag-risk-level appropriate to the operation's impact
```

```html title="❌ Missing risk level → ✅ Fix"
<!-- ❌ Missing risk level -->
<button
  axag-intent="invoice.void"
  axag-entity="invoice"
  axag-action-type="write"
>Void Invoice</button>

<!-- ✅ Risk level declared -->
<button
  axag-intent="invoice.void"
  axag-entity="invoice"
  axag-action-type="write"
  axag-risk-level="high"
  axag-confirmation-required="true"
>Void Invoice</button>
```

### AXAG-LINT-024: Risk Level Too Low for Action Type

```
Rule: AXAG-LINT-024
Severity: Warning
Message: Delete operation has risk-level below "high"
Fix: Verify risk level — most deletions should be "high" or "critical"
```

### AXAG-LINT-025: Risk Level Too High for Action Type

```
Rule: AXAG-LINT-025
Severity: Info
Message: Read operation has risk-level above "low"
Fix: Verify — reads are normally "none" unless exposing sensitive data
```

### AXAG-LINT-007: Unsupported Risk-Action Combination

```
Rule: AXAG-LINT-007
Severity: Error
Message: Invalid combination of risk-level and action-type
```

**Invalid combinations:**

| Action Type | Invalid Risk Levels | Reason |
|------------|-------------------|--------|
| `read` | `critical` | Reads should never be critical |
| `navigate` | `high`, `critical` | Navigation should not be high-risk |
| `delete` | `none` | Deletions always carry risk |

### AXAG-LINT-026: Safety Metadata Mismatch

The required safety metadata must be proportional to the risk level:

| Risk Level | Required Safety Metadata |
|-----------|------------------------|
| `none` | None |
| `low` | `idempotent` recommended |
| `medium` | `confirmation-required`, `idempotent` |
| `high` | `confirmation-required`, `preconditions`, `idempotent`, `side-effects` |
| `critical` | All of `high` + `approval-required`, `approval-roles` |

```html
<!-- ❌ High risk without required safety metadata -->
<button
  axag-intent="payment.refund"
  axag-entity="payment"
  axag-action-type="write"
  axag-risk-level="high"
>Refund</button>

<!-- ✅ High risk with proportional safety metadata -->
<button
  axag-intent="payment.refund"
  axag-entity="payment"
  axag-action-type="write"
  axag-risk-level="high"
  axag-required-parameters='["payment_id","amount"]'
  axag-preconditions='["payment exists","amount within refund limit"]'
  axag-postconditions='["refund initiated","customer notified"]'
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["payment_reversal","accounting_entry"]'
  axag-scope="tenant"
>Refund</button>
```

## Risk Assessment Checklist

When assigning a risk level, consider:

- [ ] Does this operation modify persistent state?
- [ ] Is the operation reversible?
- [ ] Does it affect financial records or payments?
- [ ] Could it affect other users or tenants?
- [ ] Does it trigger external side effects (emails, webhooks)?
- [ ] Does it require regulatory compliance?
- [ ] Could repeated execution cause harm?

## CI Integration

```yaml
- name: Validate risk levels
  run: npx axag-lint src --format github
```

## Next Steps

- [Contradictory Annotation Detection](/docs/validation/contradictory-annotation-detection)
- [Common Validation Failures](/docs/validation/common-failures)
- [Remediation Guidance](/docs/validation/remediation-guidance)

## Common Validation Failures

Source: https://axag.org/docs/validation/common-failures

This page catalogs the most frequent AXAG validation failures, their causes, and how to fix them.

## Structural Failures

### 1. Missing Required Attributes

**Error**: `AXAG-LINT-001: Element has axag-* attributes but is missing axag-intent`

**Cause**: An element has some `axag-*` attributes but is missing one of the three required attributes (`axag-intent`, `axag-entity`, `axag-action-type`).

**Fix**: Add the missing attribute.
```html title="❌ Missing required attributes → ✅ Fix"
<!-- ❌ Bad -->
<button axag-entity="product" axag-action-type="read">Search</button>

<!-- ✅ Good -->
<button axag-intent="product.search" axag-entity="product" axag-action-type="read">Search</button>
```

### 2. Invalid JSON in Attributes

**Error**: `AXAG-LINT-009: Invalid JSON in axag-required-parameters`

**Cause**: JSON array/object attributes use single quotes or have syntax errors.

**Fix**: Use valid JSON with proper quoting.
```html title="❌ Invalid JSON quotes → ✅ Fix"
<!-- ❌ Bad: single quotes -->
<button axag-required-parameters="['query', 'page']">Search</button>

<!-- ✅ Good: double quotes (attribute in single quotes) -->
<button axag-required-parameters='["query", "page"]'>Search</button>
```

### 3. Invalid Enum Values

**Error**: `AXAG-LINT-004: Invalid axag-action-type value "update"`

**Cause**: Using a value not in the allowed enum set.

**Fix**: Use one of the allowed values.
```html title="❌ Invalid enum value → ✅ Fix"
<!-- ❌ Bad -->
<button axag-action-type="update">Save</button>

<!-- ✅ Good -->
<button axag-action-type="write">Save</button>
```

## Semantic Failures

### 4. Missing Safety Metadata

**Error**: `AXAG-LINT-006: Element with risk_level "high" is missing confirmation_required`

**Cause**: High or critical risk operations should require confirmation.

**Fix**: Add `axag-confirmation-required="true"`.
```html title="❌ Missing safety metadata → ✅ Fix"
<!-- ❌ Bad -->
<button axag-intent="account.delete" axag-risk-level="high">Delete</button>

<!-- ✅ Good -->
<button axag-intent="account.delete" axag-risk-level="high"
        axag-confirmation-required="true">Delete</button>
```

### 5. Overlapping Parameters

**Error**: `AXAG-LINT-008: Parameter "email" appears in both required and optional`

**Cause**: A parameter name exists in both `axag-required-parameters` and `axag-optional-parameters`.

**Fix**: Move the parameter to the correct list — it's either required or optional, not both.

### 6. Missing Idempotency Declaration

**Error**: `AXAG-LINT-007: Write action missing axag-idempotent declaration`

**Cause**: All write and delete operations should declare whether they're idempotent.

**Fix**: Add `axag-idempotent="true"` or `axag-idempotent="false"`.

### 7. Approval Without Roles

**Error**: `AXAG-LINT-012: axag-approval-required is true but axag-approval-roles is missing`

**Cause**: Declaring an operation requires approval without specifying who can approve.

**Fix**: Add `axag-approval-roles` with the list of authorized roles.

## Cross-Reference Failures

### 8. Intent Not in Manifest

**Error**: `AXAG-LINT-010: Intent "cart.remove_item" not found in manifest`

**Cause**: An annotation references an intent that doesn't exist in the Semantic Manifest.

**Fix**: Either add the intent to the manifest, or fix the typo in the annotation.

### 9. Parameter Mismatch

**Error**: Parameter "user_role" in annotation not declared in manifest for intent "user.create"

**Cause**: The annotation references a parameter that the manifest doesn't define.

**Fix**: Synchronize parameters between annotations and manifest.

## Manifest Failures

### 10. Invalid Intent Format

**Error**: Intent "productSearch" does not match pattern `^[a-z_]+\.[a-z_]+$`

**Cause**: Intent must use `entity.action` format with snake_case.

**Fix**: Rename to `product.search`.

## Remediation Guidance

Source: https://axag.org/docs/validation/remediation-guidance

When AXAG validation produces errors or warnings, this page provides step-by-step guidance to fix common issues and bring your annotations into conformance.

## Remediation Workflow

```mermaid
graph TD
    A[Run Validation] --> B{Errors?}
    B -->|Yes| C[Categorize Errors]
    C --> D{Structural?}
    D -->|Yes| E[Fix attributes]
    D -->|No| F{Semantic?}
    F -->|Yes| G[Fix safety/constraints]
    F -->|No| H{Cross-ref?}
    H -->|Yes| I[Sync manifest]
    E --> J[Re-run Validation]
    G --> J
    I --> J
    B -->|No| K[✅ Pass]
    J --> B
```

## Step 1: Fix Structural Errors First

Structural errors prevent the validator from analyzing your annotations further. Fix these first:

1. **Add missing required attributes**: Every annotated element needs `axag-intent`, `axag-entity`, `axag-action-type`
2. **Fix JSON syntax**: Validate JSON strings in parameter attributes with a JSON linter
3. **Correct enum values**: Use only allowed values for `axag-action-type` (`read`, `write`, `delete`) and `axag-risk-level` (`none`, `low`, `medium`, `high`, `critical`)

## Step 2: Resolve Semantic Warnings

Once structural errors are cleared, address semantic issues:

### Risk/Confirmation Matrix
Ensure your risk levels and confirmation requirements align:

| Risk Level | `confirmation_required` | `approval_required` |
|------------|------------------------|---------------------|
| `none` | Not needed | Not needed |
| `low` | Not needed | Not needed |
| `medium` | Recommended | Not needed |
| `high` | **MUST** | Recommended |
| `critical` | **MUST** | **MUST** |

### Idempotency Checklist
For each write/delete operation, determine idempotency:
- **Idempotent** if calling it twice with the same parameters produces the same result (e.g., set status, update fields, soft delete)
- **Not idempotent** if calling it twice creates duplicate effects (e.g., create record, add to cart, send notification)

### Scope Checklist
For operations that access data, declare the scope:
- `public` — No authentication required
- `user` — Scoped to the authenticated user
- `tenant` — Scoped to the user's organization
- `global` — Affects all tenants (rare, admin-only)

## Step 3: Synchronize Manifest

After fixing annotations, ensure the Semantic Manifest is in sync:

```bash title="Regenerate manifest after fixes"
# Regenerate manifest from annotations
npx axag generate src --manifest axag-manifest.json

# Or manually add missing intents to existing manifest
# Edit axag-manifest.json and add the missing action definitions
```

## Step 4: Auto-Fix Where Possible

Some validators support auto-fixing:

```bash
# Auto-fix common issues
npx axag-lint src/ --fix

# What auto-fix handles:
# - Add missing axag-idempotent="false" to write actions
# - Add axag-confirmation-required="true" to high/critical risk
# - Fix JSON attribute formatting
# - Normalize intent naming to snake_case
```

## Step 5: Verify with Conformance Check

After remediation, verify your target conformance level:

```bash
# Check target level
npx axag validate src --level intermediate --strict

# Verbose output shows:
# ✓ 45/45 actions have intent declared
# ✓ 45/45 actions have parameters with types
# ✓ 42/45 actions have risk level declared
# ✗ 3 actions missing risk level (list below)
#   - admin.view_logs
#   - config.list_options
#   - help.search
```

## Incremental Adoption

You don't have to fix everything at once. Start with:

1. **Week 1**: Fix all structural errors (Level 1 / Basic)
2. **Week 2**: Add parameter types and risk levels (Level 2 / Intermediate)
3. **Week 3**: Add preconditions, postconditions, and safety metadata (Level 3 / Full)

Set up CI to enforce the current target level and increase it as your team progresses.


# Governance

## Ownership Model

Source: https://axag.org/docs/governance/ownership-model

AXAG annotations and Semantic Manifests are living artifacts that require clear ownership, maintenance responsibilities, and decision-making authority.

## Who Owns What

| Artifact | Owner | Reviewer | Consumer |
|----------|-------|----------|----------|
| AXAG Specification | Standards Body | Community | Everyone |
| AXAG Annotations (per page) | Feature Team | Platform Team | Agent Frameworks |
| Semantic Manifest | Platform Team | Security Team | Agent Runtime |
| Generated Tools | Platform Team | Feature Team | AI Agents |
| Validation Rules | Platform Team | All Teams | CI/CD Pipeline |

## Annotation Ownership

Annotations belong to the team that owns the feature:
- The **shopping cart** team owns `cart.*` annotations
- The **billing** team owns `billing.*` annotations
- The **admin** team owns `admin.*` annotations

### Responsibilities
- Keep annotations in sync with UI changes
- Update parameters when form fields change
- Review risk levels when business logic changes
- Respond to cross-reference validation failures

## Manifest Ownership

The Semantic Manifest is owned by the **platform/API team** because:
- It serves as the contract between UI and agents
- Changes affect all downstream consumers (tool generation, agent behavior)
- It requires coordination across feature teams
- Security review is mandatory for risk level changes

## Change Authority

### Who Can Change What

| Change Type | Who Can Propose | Who Approves |
|-------------|----------------|--------------|
| New annotation | Feature team | Platform team |
| Change risk level | Feature or Security | Security team |
| Add new entity | Feature team | Architecture team |
| Deprecate intent | Platform team | All consuming teams |
| Change safety boundary | Security team | Security + Platform |
| Schema version bump | Standards body | Governance committee |

## RACI Matrix

| Activity | Responsible | Accountable | Consulted | Informed |
|----------|------------|-------------|-----------|----------|
| Write annotations | Feature Dev | Feature Lead | Platform | Agent Teams |
| Review annotations | Platform | Platform Lead | Security | Feature |
| Generate manifest | Platform | Platform Lead | Feature | Agent Teams |
| Validate in CI | DevOps | Platform Lead | All | All |
| Security review | Security | Security Lead | Platform | Feature |
| Version release | Platform | Governance | All | All |

## Change Review Workflow

Source: https://axag.org/docs/governance/change-review-workflow

All changes to AXAG annotations, manifests, and generated tools follow a structured review workflow to ensure safety, consistency, and backward compatibility.

## Standard Review Flow

```mermaid
graph TD
    A[Developer proposes change] --> B[Create PR with annotation changes]
    B --> C[CI runs AXAG validation]
    C --> D{Validation passes?}
    D -->|No| E[Fix errors, push again]
    E --> C
    D -->|Yes| F{Risk level changed?}
    F -->|Yes| G[Security review required]
    F -->|No| H[Platform team review]
    G --> H
    H --> I{Manifest changes?}
    I -->|Yes| J[Regenerate manifest + tools]
    I -->|No| K[Approve & merge]
    J --> L[Agent team notified]
    L --> K
```

## Review Triggers

| Change | Reviews Required |
|--------|-----------------|
| New annotation (low risk) | Platform team |
| New annotation (high/critical risk) | Platform + Security |
| Risk level increase | Security team |
| Risk level decrease | Platform team |
| New entity type | Architecture + Platform |
| Parameter schema change | Platform + Feature |
| Safety metadata change | Security team |
| Manifest version bump | All stakeholders |

## PR Template for AXAG Changes

```markdown
## AXAG Change Request

### Change Type
- [ ] New annotation
- [ ] Modify existing annotation
- [ ] Remove annotation
- [ ] Manifest schema change
- [ ] Safety metadata change

### Affected Intents
- `entity.action_name`

### Risk Assessment
- Previous risk level: ___
- New risk level: ___
- Reason for change: ___

### Breaking Changes
- [ ] This change is backward-compatible
- [ ] This change breaks existing tool consumers (migration guide attached)

### Security Checklist
- [ ] Risk level is appropriate for the operation
- [ ] Confirmation is required for high/critical risk
- [ ] Approval roles are specified where needed
- [ ] Scope boundaries are declared
- [ ] Preconditions are machine-checkable

### Testing
- [ ] Static validation passes
- [ ] Manifest regenerated and validated
- [ ] Generated tools tested with agent framework
```

## Emergency Change Process

For urgent fixes (e.g., security vulnerability in annotations):

1. Create hotfix branch
2. Fix the annotation
3. Get Security team approval (async, within 1 hour)
4. Merge with expedited review
5. Create follow-up ticket for full review

## Version Policy

Source: https://axag.org/docs/governance/version-policy

The AXAG standard, Semantic Manifests, and generated tools all follow semantic versioning with clear policies for backward compatibility and migration.

## Versioning Scheme

```
MAJOR.MINOR.PATCH[-PRERELEASE]
```

- **MAJOR**: Breaking changes to required fields or fundamental semantics
- **MINOR**: New optional fields, new conformance rules, new lint rules
- **PATCH**: Documentation fixes, typo corrections, schema bug fixes
- **PRERELEASE**: Draft versions (e.g., `1.0.0-rc.1`)

## Current Version

The current AXAG specification version is **1.0.0**.

## Version Lifecycle

```mermaid
graph LR
    A[Draft] --> B[Release Candidate]
    B --> C[Stable]
    C --> D[Maintained]
    D --> E[Deprecated]
    E --> F[Retired]
```

| Phase | Duration | Guarantees |
|-------|----------|------------|
| Draft | Until community review complete | No stability guarantees |
| Release Candidate | 2–4 weeks | No new features, bug fixes only |
| Stable | Indefinite | Backward-compatible within major version |
| Maintained | Until next major version + 12 months | Security fixes only |
| Deprecated | 12 months from deprecation notice | No changes, migration guide available |
| Retired | After deprecation period | Removed from documentation |

## Manifest Versioning

Each Semantic Manifest includes a version field:

```json
{
  "version": "1.1.0",
  "conformance": "intermediate",
  "actions": []
}
```

Agents MUST check the manifest version and verify they support it before consuming the manifest.

## Backward Compatibility Rules

### Within a Minor Version
- New optional fields MAY be added
- Existing fields MUST NOT be removed
- Existing field semantics MUST NOT change
- New enum values MAY be added to existing enums
- New lint rules MAY be added as warnings

### Across Major Versions
- Fields MAY be removed (with 12-month deprecation notice)
- Field semantics MAY change
- Required fields MAY be added
- Enum values MAY be removed
- Migration guide MUST be provided

## Backward Compatibility

Source: https://axag.org/docs/governance/backward-compatibility

AXAG takes backward compatibility seriously. Agents consuming AXAG manifests must be able to rely on stable contracts. This page defines what constitutes a breaking change and how backward compatibility is maintained.

## What Is a Breaking Change

A change is **breaking** if it causes existing, conformant consumers to fail:

| Change | Breaking? | Reason |
|--------|-----------|--------|
| Add optional field to manifest | No | Consumers ignore unknown fields |
| Add new enum value | No | Consumers should handle unknown values gracefully |
| Remove a required field | **Yes** | Consumers depend on it |
| Rename a field | **Yes** | Consumers reference old name |
| Change field type | **Yes** | Consumers parse with old type |
| Remove an enum value | **Yes** | Consumers may send removed value |
| Change `axag-intent` format | **Yes** | All intent parsing breaks |
| Add new required field | **Yes** | Existing manifests become invalid |
| Change risk level semantics | **Yes** | Safety behavior changes |

## Non-Breaking Changes

These changes are always safe:
- Adding new optional `axag-*` attributes
- Adding new optional fields to manifest actions
- Adding new lint rules as warnings (not errors)
- Adding new conformance level criteria
- Adding new entity types
- Adding new use case documentation

## Compatibility Matrix

| Consumer Version | Manifest 0.1.x | Manifest 0.2.x | Manifest 1.0.x |
|-----------------|----------------|----------------|----------------|
| Agent v0.1.x | ✅ Full | ⚠️ Partial | ❌ Incompatible |
| Agent v0.2.x | ✅ Full | ✅ Full | ❌ Incompatible |
| Agent v1.0.x | ✅ Full | ✅ Full | ✅ Full |

## Robustness Principle

Agents consuming AXAG manifests SHOULD follow Postel's Law:

> Be conservative in what you send, be liberal in what you accept.

- **Producers** (annotation authors): Follow the spec strictly
- **Consumers** (agents): Handle unknown fields gracefully, don't fail on extra data

## Deprecation Strategy

Source: https://axag.org/docs/governance/deprecation-strategy

When AXAG fields, intents, or patterns need to be removed, a structured deprecation process ensures consumers have time to migrate.

## Deprecation Timeline

```mermaid
gantt
    title Deprecation Timeline
    dateFormat YYYY-MM
    section Phase
    Deprecation Notice    :a1, 2024-01, 1M
    Warning in Validators :a2, after a1, 3M
    Error in Validators   :a3, after a2, 6M
    Removal               :a4, after a3, 2M
```

| Phase | Duration | Action |
|-------|----------|--------|
| Notice | Day 0 | Deprecation announced in changelog, docs, and release notes |
| Warning | Months 1–3 | Validators emit deprecation warnings; code continues to work |
| Error | Months 4–9 | Validators emit errors; code still works at runtime |
| Removal | Month 12 | Field/feature removed from spec and validators |

## Deprecation Notice Format

```json
{
  "deprecated": {
    "field": "axag-side-effects",
    "since": "0.2.0",
    "removal": "1.0.0",
    "reason": "Replaced by axag-postconditions with structured side-effect declarations",
    "migration": "Move side-effects into axag-postconditions array with 'side_effect:' prefix"
  }
}
```

## Deprecation in Documentation

Deprecated features are marked in docs with:
- ⚠️ **Deprecated** banner at the top of the relevant page
- Strikethrough in reference tables
- Link to migration guide
- Replacement recommendation

## Migration Guides

Every deprecation includes a migration guide with:
1. What is changing and why
2. Before/after code examples
3. Automated migration script (where possible)
4. Timeline for removal

## How to Check for Deprecations

```bash
# Check for deprecated usage
npx axag-lint src/ --check-deprecations

# Output
⚠️ DEPRECATED: axag-side-effects at src/Cart.tsx:42
   Use axag-postconditions instead (removal in v1.0.0)
   Migration: https://axag.org/docs/governance/deprecation-strategy#migration-guides
```

## Release Notes Model

Source: https://axag.org/docs/governance/release-notes-model

Every AXAG specification release includes structured release notes that communicate changes clearly to all stakeholders.

## Release Note Structure

```markdown
# AXAG v0.2.0 Release Notes

**Release Date**: 2024-07-01
**Status**: Stable
**Previous Version**: 1.0.0

## Highlights
- Brief summary of the most important changes

## New Features
- Feature descriptions with links to documentation

## Breaking Changes
- ⚠️ List of breaking changes with migration guides

## Deprecations
- Features deprecated in this release with removal timeline

## Bug Fixes
- Validation and schema fixes

## Documentation
- New or updated documentation pages

## Migration Guide
- Step-by-step upgrade instructions
```

## Change Categories

| Category | Label | Description |
|----------|-------|-------------|
| New Feature | `feature` | New capability added |
| Breaking Change | `breaking` | Requires consumer changes |
| Deprecation | `deprecated` | Feature scheduled for removal |
| Bug Fix | `fix` | Correction to existing behavior |
| Documentation | `docs` | Documentation-only change |
| Internal | `internal` | Tooling, CI, build changes |

## Audience-Specific Sections

Release notes include audience-specific impact sections:

### For Annotation Authors
What annotations to update, new attributes available, deprecated attributes.

### For Agent Framework Developers
What manifest changes affect tool generation, new fields to consume, removed fields.

### For Platform/DevOps Teams
What CI rules changed, new validation requirements, infrastructure changes.

## Changelog

The project maintains a `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/) format:

```markdown
# Changelog

## [Unreleased]

## [0.2.0] - 2024-07-01
### Added
- `axag-tenant-boundary` attribute for multi-tenant scoping
- New lint rule AXAG-LINT-013 for tenant boundary validation
### Changed
- `axag-side-effects` now supports structured array syntax
### Deprecated
- Plain string `axag-side-effects` (use structured format)
### Fixed
- Schema validation for nested parameter objects

## [1.0.0] - 2024-01-15
### Added
- Initial specification draft
- Core annotation attributes
- Semantic Manifest schema
- Tool generation mapping rules
```

## Standard Evolution Process

Source: https://axag.org/docs/governance/standard-evolution-process

The AXAG standard evolves through a structured proposal, review, and adoption process. Anyone can propose changes, but all changes go through community review.

## Proposal Process

### 1. AXAG Enhancement Proposal (AEP)

Changes to the standard are proposed as AEPs:

```markdown
# AEP-XXXX: [Title]

**Author**: [Name]
**Status**: Draft | Review | Accepted | Rejected | Withdrawn
**Created**: YYYY-MM-DD
**Target Version**: X.Y.Z

## Abstract
One-paragraph summary.

## Motivation
Why is this change needed?

## Specification
Detailed technical specification of the change.

## Backward Compatibility
Impact on existing consumers.

## Reference Implementation
Link to proof-of-concept or reference implementation.

## Alternatives Considered
Other approaches evaluated and why they were rejected.
```

### 2. Review Process

```mermaid
graph TD
    A[Submit AEP] --> B[Community Discussion - 2 weeks]
    B --> C[Working Group Review]
    C --> D{Consensus?}
    D -->|Yes| E[Reference Implementation]
    E --> F[Final Review - 1 week]
    F --> G[Accepted]
    D -->|No| H{Revise?}
    H -->|Yes| I[Author Revises]
    I --> B
    H -->|No| J[Rejected]
```

### 3. Implementation

Accepted AEPs are implemented in:
1. Schema updates (JSON Schema)
2. Validator updates (lint rules)
3. Documentation updates (this site)
4. Reference tooling updates

## Working Groups

| Group | Focus | Members |
|-------|-------|---------|
| Core Spec | Annotation vocabulary, manifest schema | Spec authors, platform engineers |
| Safety & Security | Risk levels, confirmation, approval, tenant boundaries | Security engineers, compliance |
| Tooling | Validators, generators, CI integration | DevTools engineers |
| Use Cases | Domain-specific patterns, cross-domain comparison | Domain experts, solution architects |
| Governance | Version policy, deprecation, release process | Standards body, community leads |

## Decision Making

- **Consensus-driven**: Major changes require working group consensus
- **Lazy consensus**: Minor changes accepted if no objections within 2 weeks
- **Voting**: If consensus cannot be reached, simple majority of working group members
- **Veto**: Security-critical changes can be vetoed by the Safety & Security working group

## Conformance Adoption Levels

Source: https://axag.org/docs/governance/conformance-adoption-levels

Organizations adopt AXAG incrementally. These adoption levels provide a roadmap from initial experimentation to full production deployment.

## Adoption Maturity Model

```mermaid
graph LR
    A[Level 0: Unaware] --> B[Level 1: Exploring]
    B --> C[Level 2: Piloting]
    C --> D[Level 3: Scaling]
    D --> E[Level 4: Optimizing]
```

### Level 0: Unaware
- No AXAG annotations
- Agents rely on scraping, screenshots, or custom integrations
- High maintenance, brittle, non-portable

### Level 1: Exploring
- Team awareness of AXAG
- Reading documentation, evaluating fit
- No production annotations yet
- **Goal**: Understand the value proposition

### Level 2: Piloting
- 1–3 pages annotated with AXAG attributes
- Basic conformance (Level 1: required fields only)
- Manual manifest creation
- Testing with a single agent framework
- **Goal**: Prove the concept works

### Level 3: Scaling
- Annotations on all major user flows
- Intermediate conformance (Level 2: parameters, risk, idempotency)
- Automated manifest generation in CI
- Multiple agent frameworks consuming the manifest
- Validation integrated into PR review
- **Goal**: Production-grade agent support

### Level 4: Optimizing
- Full conformance (Level 3: preconditions, safety, tenant boundaries)
- Runtime validation enforcing contracts
- Comprehensive test coverage for annotation accuracy
- Cross-domain consistency validated
- Contributing back to the standard
- **Goal**: Best-in-class agent experience

## Adoption Checklist

### Pilot Phase
- [ ] Read the Introduction and Getting Started sections
- [ ] Annotate one read-only action (e.g., search)
- [ ] Annotate one write action (e.g., create)
- [ ] Create a minimal Semantic Manifest
- [ ] Generate one MCP tool from the manifest
- [ ] Test with an agent framework

### Scaling Phase
- [ ] Annotate all customer-facing actions
- [ ] Add parameter types and constraints
- [ ] Declare risk levels for all write/delete operations
- [ ] Set up CI validation (AXAG-LINT rules)
- [ ] Generate full manifest automatically
- [ ] Register tools with agent runtime

### Optimizing Phase
- [ ] Add preconditions and postconditions
- [ ] Declare side-effects for all write operations
- [ ] Implement runtime validation
- [ ] Add tenant boundary declarations
- [ ] Achieve full conformance certification
- [ ] Contribute use cases back to AXAG community

## Measuring Progress

Track adoption with these metrics:

| Metric | Formula | Target |
|--------|---------|--------|
| Annotation Coverage | Annotated actions ÷ Total actions | > 90% |
| Conformance Score | Fields declared ÷ Fields required at level | 100% at target level |
| Manifest Freshness | Time since last manifest update | < 1 sprint |
| Validation Pass Rate | CI runs passed ÷ Total CI runs | > 95% |
| Agent Success Rate | Successful tool calls ÷ Total tool calls | > 98% |


# Reference

## Schema Reference

Source: https://axag.org/docs/reference/schema-reference

Complete JSON Schema reference for all AXAG artifacts.

## Annotation Attribute Schema

Every AXAG-annotated HTML element uses the following attributes:

### Required Attributes

| Attribute | Type | Values | Description |
|-----------|------|--------|-------------|
| `axag-intent` | string | `entity.action` pattern | Canonical intent identifier |
| `axag-entity` | string | snake_case | Entity this action operates on |
| `axag-action-type` | string | `read` \| `write` \| `delete` | Operation category |

### Recommended Attributes

| Attribute | Type | Values | Description |
|-----------|------|--------|-------------|
| `axag-description` | string | Free text | Human-readable action description |
| `axag-risk-level` | string | `none` \| `low` \| `medium` \| `high` \| `critical` | Risk classification |
| `axag-idempotent` | boolean | `true` \| `false` | Whether repeated calls are safe |
| `axag-required-parameters` | JSON array | `["param1","param2"]` | Parameters that MUST be provided |
| `axag-optional-parameters` | JSON array | `["param1","param2"]` | Parameters that MAY be provided |

### Safety Attributes

| Attribute | Type | Values | Description |
|-----------|------|--------|-------------|
| `axag-confirmation-required` | boolean | `true` \| `false` | Whether user confirmation is needed |
| `axag-approval-required` | boolean | `true` \| `false` | Whether role-based approval is needed |
| `axag-approval-roles` | JSON array | `["role1","role2"]` | Roles authorized to approve |
| `axag-preconditions` | JSON array | `["condition"]` | Conditions that MUST be true before execution |
| `axag-postconditions` | JSON array | `["condition"]` | Conditions guaranteed after successful execution |
| `axag-side-effects` | JSON array | `["effect"]` | Side-effects of execution |

### Scope Attributes

| Attribute | Type | Values | Description |
|-----------|------|--------|-------------|
| `axag-scope` | string | `public` \| `user` \| `tenant` \| `global` | Data access scope |
| `axag-tenant-boundary` | string | `strict` \| `relaxed` | Tenant isolation enforcement |

### Execution Attributes

| Attribute | Type | Values | Description |
|-----------|------|--------|-------------|
| `axag-async` | boolean | `true` \| `false` | Whether operation is asynchronous |

## Manifest Schema

See [Schema Conformance](/docs/validation/schema-conformance) for the full JSON Schema definition.

## Tool Schema

Generated MCP tools follow this structure:

```json
{
  "name": "entity_action",
  "description": "Description of the action",
  "input_schema": {
    "type": "object",
    "properties": { "param_name": { "type": "string", "description": "Parameter description" } },
    "required": ["param_name"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "medium",
    "idempotent": true,
    "confirmation_required": true,
    "approval_required": false,
    "side_effects": ["state_change"],
    "preconditions": ["entity exists"],
    "source_intent": "entity.action",
    "source_entity": "entity"
  }
}
```

## Annotation Attributes Reference

Source: https://axag.org/docs/reference/annotation-attributes

Complete reference for all `axag-*` HTML attributes with usage examples.

## axag

**Type**: `macro`  
**Required**: MAY

Shorthand for the identity and safety attributes below. See [Macro Syntax](/docs/specification/macro-syntax).

```html title="axag — macro shorthand"
axag="write:user.deactivate!critical?approval&roles=security_admin"
```

## axag-intent

**Type**: `string`  
**Required**: MUST  
**Pattern**: `^[a-z_]+\.[a-z_]+$`

Canonical identifier for the action's intent. Uses `entity.action` naming convention.

```html title="axag-intent — entity.action format"
axag-intent="product.search"
axag-intent="cart.add_item"
axag-intent="order.track"
axag-intent="account.delete"
```

## axag-entity

**Type**: `string`  
**Required**: MUST  
**Pattern**: `^[a-z_]+$`

The entity this action operates on.

```html title="axag-entity — domain entity names"
axag-entity="product"
axag-entity="cart"
axag-entity="user"
axag-entity="billing"
```

## axag-action-type

**Type**: `enum`  
**Required**: MUST  
**Values**: `read`, `write`, `delete`, `navigate`

```html title="axag-action-type — operation classification"
axag-action-type="read"    <!-- Query, search, list, get, view -->
axag-action-type="write"   <!-- Create, update, submit, schedule -->
axag-action-type="delete"  <!-- Remove, cancel, deactivate -->
axag-action-type="navigate"  <!-- Change view without mutating data -->
```

## axag-description

**Type**: `string`  
**Required**: SHOULD  

Human-readable description of what the action does. Used in generated tool descriptions.

```html title="axag-description — human-readable action summary"
axag-description="Search the product catalog with text query and optional filters"
```

## axag-risk-level

**Type**: `enum`  
**Required**: SHOULD  
**Values**: `none`, `low`, `medium`, `high`, `critical`

| Level | Criteria | Example |
|-------|----------|---------|
| `none` | Read-only, no side-effects | Search, list, view |
| `low` | Write with reversible effects | Create draft, add to cart |
| `medium` | Write with moderate consequences | Submit form, update record |
| `high` | Write with significant consequences | Delete data, process refund |
| `critical` | Write with financial/security/legal impact | Billing change, disable MFA |

## axag-idempotent

**Type**: `boolean`  
**Required**: SHOULD (for write/delete)

Whether calling the operation twice with the same parameters produces the same result.

```html title="axag-idempotent — safe to retry?"
axag-idempotent="true"   <!-- Update status, set value, soft delete -->
axag-idempotent="false"  <!-- Create record, add to cart, send email -->
```

## axag-required-parameters

**Type**: `JSON string[]`  
**Required**: SHOULD

```html title="axag-required-parameters"
axag-required-parameters='["product_id","quantity"]'
```

## axag-optional-parameters

**Type**: `JSON string[]`  
**Required**: MAY

```html title="axag-optional-parameters"
axag-optional-parameters='["variant_id","gift_wrap"]'
```

## axag-preconditions

**Type**: `JSON string[]`  
**Required**: MAY

```html title="axag-preconditions — what must be true before execution"
axag-preconditions='["product must be in stock","user must be authenticated"]'
```

## axag-postconditions

**Type**: `JSON string[]`  
**Required**: MAY

```html title="axag-postconditions — guaranteed state after execution"
axag-postconditions='["item added to cart","cart total updated"]'
```

## axag-confirmation-required

**Type**: `boolean`  
**Required**: MUST (when risk_level is high or critical)

```html title="axag-confirmation-required — user must confirm"
axag-confirmation-required="true"
```

## axag-approval-required

**Type**: `boolean`  
**Required**: MUST (when approval gate exists)

```html title="axag-approval-required — needs human approval gate"
axag-approval-required="true"
```

## axag-approval-roles

**Type**: `JSON string[]`  
**Required**: MUST (when approval-required is true)

```html title="axag-approval-roles — who can approve"
axag-approval-roles='["super_admin","security_admin"]'
```

## axag-side-effects

**Type**: `JSON string[]`  
**Required**: SHOULD (for write/delete with external effects)

```html title="axag-side-effects — external consequences"
axag-side-effects='["email_notification","inventory_update","refund_processing"]'
```

## axag-scope

**Type**: `enum`  
**Required**: SHOULD  
**Values**: `public`, `user`, `tenant`, `global`

```html title="axag-scope — visibility boundary"
axag-scope="tenant"
```

## axag-tenant-boundary

**Type**: `enum`  
**Required**: SHOULD (for tenant-scoped operations)  
**Values**: `strict`, `relaxed`

```html title="axag-tenant-boundary — cross-tenant enforcement"
axag-tenant-boundary="strict"
```

## axag-async

**Type**: `boolean`  
**Required**: MAY

```html title="axag-async — long-running operation"
axag-async="true"
```

## Reserved Terms

Source: https://axag.org/docs/reference/reserved-terms

The following terms are reserved in the AXAG specification. Custom annotations MUST NOT use these names for different purposes.

## Reserved Attribute Prefixes

All attributes starting with `axag-` are reserved by the AXAG specification:

- `axag-intent`
- `axag-entity`
- `axag-action-type`
- `axag-description`
- `axag-risk-level`
- `axag-idempotent`
- `axag-required-parameters`
- `axag-optional-parameters`
- `axag-preconditions`
- `axag-postconditions`
- `axag-side-effects`
- `axag-confirmation-required`
- `axag-approval-required`
- `axag-approval-roles`
- `axag-scope`
- `axag-tenant-boundary`
- `axag-async`

Custom extensions MUST use the `axag-x-` prefix:

```html
axag-x-my-custom-attribute="value"
```

## Reserved Action Types

| Value | Meaning |
|-------|---------|
| `read` | Query, search, list, get, view — no state change |
| `write` | Create, update, submit, schedule — state change |
| `delete` | Remove, cancel, deactivate — destructive state change |

## Reserved Risk Levels

| Value | Meaning |
|-------|---------|
| `none` | No risk — read-only operations |
| `low` | Minimal risk — easily reversible |
| `medium` | Moderate risk — may require confirmation |
| `high` | Significant risk — MUST require confirmation |
| `critical` | Maximum risk — MUST require confirmation AND approval |

## Reserved Scope Values

| Value | Meaning |
|-------|---------|
| `public` | No authentication required |
| `user` | Scoped to the authenticated user |
| `tenant` | Scoped to the user's organization |
| `global` | Cross-tenant, typically admin-only |

## Reserved Manifest Fields

These field names are reserved in the Semantic Manifest JSON:

- `version`, `generated_at`, `source`, `conformance`, `actions`
- `intent`, `entity`, `operation_id`, `action_type`, `description`
- `required_parameters`, `optional_parameters`, and parameter fields `name`, `type`, `enum`, `min`, `max`, `minLength`, `maxLength`, `pattern`, `format`, `default`, `items`, `properties`
- `preconditions`, `postconditions`, `side_effects`
- `risk_level`, `idempotent`, `confirmation_required`, `approval_required`, `approval_roles`
- `scope`, `tenant_boundary`, `required_roles`, `async`
- `element_selector`, `source_file`, `source_line`

## Reserved Error Codes

All error codes starting with `AXAG_` are reserved:

- `AXAG_VALIDATION_ERROR`
- `AXAG_MISSING_PARAM`
- `AXAG_INVALID_TYPE`
- `AXAG_OUT_OF_RANGE`
- `AXAG_INVALID_ENUM`
- `AXAG_PRECONDITION_FAILED`
- `AXAG_CONFIRMATION_MISSING`
- `AXAG_APPROVAL_MISSING`
- `AXAG_SCOPE_VIOLATION`
- `AXAG_TENANT_BOUNDARY`
- `AXAG_ROLE_INSUFFICIENT`

## Reserved Lint Rule IDs

All IDs matching `AXAG-LINT-XXX` are reserved. Custom rules should use `AXAG-CUSTOM-XXX`.

## Error Codes Reference

Source: https://axag.org/docs/reference/error-codes

Complete reference of all AXAG error codes used in validation, runtime enforcement, and agent communication.

## Validation Error Codes

These codes are emitted by static validators and CI lint tools.

| Code | Severity | Description |
|------|----------|-------------|
| `AXAG-LINT-001` | Error | Missing `axag-intent` on annotated element |
| `AXAG-LINT-002` | Error | Missing `axag-entity` on annotated element |
| `AXAG-LINT-003` | Error | Missing `axag-action-type` on annotated element |
| `AXAG-LINT-004` | Error | Invalid `axag-action-type` value |
| `AXAG-LINT-005` | Error | Invalid `axag-risk-level` value |
| `AXAG-LINT-006` | Warning | High/critical risk missing `confirmation_required` |
| `AXAG-LINT-007` | Warning | Write/delete missing `axag-idempotent` declaration |
| `AXAG-LINT-008` | Error | Overlapping required and optional parameters |
| `AXAG-LINT-009` | Error | Invalid JSON in parameter attribute |
| `AXAG-LINT-010` | Warning | Intent not found in Semantic Manifest |
| `AXAG-LINT-011` | Warning | Missing `axag-scope` on tenant-sensitive action |
| `AXAG-LINT-012` | Error | `approval-required` without `approval-roles` |

## Runtime Error Codes

These codes are returned by AXAG-aware runtimes when contract violations occur.

| Code | Category | HTTP Status | Description |
|------|----------|-------------|-------------|
| `AXAG_MISSING_PARAM` | Parameter | 400 | Required parameter not provided |
| `AXAG_INVALID_TYPE` | Parameter | 400 | Parameter value has wrong type |
| `AXAG_OUT_OF_RANGE` | Constraint | 400 | Numeric value outside min/max bounds |
| `AXAG_INVALID_ENUM` | Constraint | 400 | Value not in allowed enum set |
| `AXAG_INVALID_FORMAT` | Constraint | 400 | Value doesn't match declared format |
| `AXAG_PRECONDITION_FAILED` | Precondition | 412 | Precondition check failed |
| `AXAG_CONFIRMATION_MISSING` | Safety | 428 | Confirmation required but not provided |
| `AXAG_APPROVAL_MISSING` | Safety | 428 | Approval required but not provided |
| `AXAG_APPROVAL_INVALID` | Safety | 403 | Approval from unauthorized role |
| `AXAG_SCOPE_VIOLATION` | Security | 403 | Operation outside declared scope |
| `AXAG_TENANT_BOUNDARY` | Security | 403 | Cross-tenant access attempt |
| `AXAG_ROLE_INSUFFICIENT` | Authorization | 403 | Caller lacks required role |
| `AXAG_INTENT_NOT_FOUND` | Routing | 404 | Requested intent not in manifest |
| `AXAG_VERSION_MISMATCH` | Compatibility | 409 | Consumer/manifest version incompatible |
| `AXAG_RATE_LIMITED` | Throttling | 429 | Too many requests for this intent |

## Error Response Format

```json
{
  "error": {
    "code": "AXAG_PRECONDITION_FAILED",
    "type": "precondition_error",
    "message": "Precondition not met: cart must have at least one item",
    "details": {
      "intent": "cart.begin_checkout",
      "failed_precondition": "cart must have at least one item",
      "suggestion": "Add items to cart using cart.add_item before beginning checkout"
    },
    "documentation_url": "https://axag.org/docs/reference/error-codes#AXAG_PRECONDITION_FAILED"
  }
}
```

## Agent Handling Guide

| Error Code | Agent Action |
|-----------|-------------|
| `AXAG_MISSING_PARAM` | Add the missing parameter and retry |
| `AXAG_INVALID_TYPE` | Fix the parameter type and retry |
| `AXAG_OUT_OF_RANGE` | Adjust value to within bounds and retry |
| `AXAG_PRECONDITION_FAILED` | Execute prerequisite action, then retry |
| `AXAG_CONFIRMATION_MISSING` | Request user confirmation, then retry with token |
| `AXAG_APPROVAL_MISSING` | Request approval from authorized role, then retry |
| `AXAG_SCOPE_VIOLATION` | Do not retry — operation is out of scope |
| `AXAG_TENANT_BOUNDARY` | Do not retry — security violation |

## Manifest Fields Reference

Source: https://axag.org/docs/reference/manifest-fields

Every Semantic Manifest field, and the annotation attribute it is generated from. The JSON Schema that enforces these fields is described in [Manifest Schema](/docs/semantic-manifest/manifest-schema).

## Top-Level Fields

| Field | Type | Required | Filled from |
|-------|------|----------|-------------|
| `version` | string | MUST | Specification version of the generator (`"1.1.0"`) |
| `generated_at` | string (ISO 8601) | MUST | Time of generation |
| `source` | object | MUST | `url`, `paths`, `tool`, `tool_version` of the run |
| `conformance` | string | MUST | Computed — see [Conformance Levels](/docs/specification/conformance-levels) |
| `actions` | Action[] | MUST | One entry per distinct `axag-intent`, sorted by intent |

When two elements declare the same intent, generators keep the first and report the second (`AXAG-CORE-003`).

## Action Object

| Field | Type | Required | Filled from |
|-------|------|----------|-------------|
| `intent` | string | MUST | `axag-intent` |
| `entity` | string | MUST | `axag-entity`, or the part of the intent before the dot |
| `action_type` | string | MUST | `axag-action-type` (`read` when absent) |
| `description` | string | MUST | `axag-description`, or the intent in words (`cart.add_item` → `Cart Add Item`) |
| `operation_id` | string | SHOULD | `axag-operation-id`, or the intent with `.` → `_` |
| `required_parameters` | Parameter[] | SHOULD | `axag-required-parameters` |
| `optional_parameters` | Parameter[] | MAY | `axag-optional-parameters` |
| `risk_level` | string | SHOULD | `axag-risk-level` |
| `confirmation_required` | boolean | MUST (high/critical) | `axag-confirmation-required` |
| `approval_required` | boolean | MAY | `axag-approval-required` |
| `approval_roles` | string[] | MUST (if approval) | `axag-approval-roles` |
| `idempotent` | boolean | SHOULD (write/delete) | `axag-idempotent` |
| `async` | boolean | MAY | `axag-async` |
| `scope` | string | SHOULD | `axag-scope` |
| `tenant_boundary` | string | MAY | `axag-tenant-boundary` |
| `required_roles` | string[] | MAY | `axag-required-roles` |
| `preconditions` | string[] | MAY | `axag-preconditions` |
| `postconditions` | string[] | MAY | `axag-postconditions` |
| `side_effects` | string[] | MAY | `axag-side-effects` |
| `element_selector` | string | MAY | CSS path, when read from a live page |
| `source_file` / `source_line` | string / integer | MAY | Where the annotation was found |

Optional fields appear only when the annotation declares them.

## Parameter Object

Besides declared parameters, generators add parameters from bound schemas and from form controls; see [Schema Harvesting](/docs/semantic-manifest/schema-harvesting). Parameters listed by name (`'["query"]'`) become `{ "name": "query", "type": "string" }`. The object form carries types and constraints through unchanged:

```html
axag-required-parameters='[{"name":"quantity","type":"integer","min":1,"max":99}]'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | MUST | Parameter name |
| `type` | string | MUST | `string`, `number`, `integer`, `boolean`, `array`, `object` |
| `description` | string | MAY | Parameter description |
| `enum` | any[] | MAY | Allowed values |
| `min` / `max` | number | MAY | Numeric bounds |
| `minLength` / `maxLength` | integer | MAY | String length bounds |
| `pattern` | string | MAY | Regular expression the value must match |
| `format` | string | MAY | `email`, `url`, `date`, `datetime`, `uuid` |
| `default` | any | MAY | Value used when omitted |
| `items` | object | MAY | JSON Schema for array elements |
| `properties` | object | MAY | JSON Schema properties for objects |
| `source` | string | MAY | `harvested:html`, `zod` or `openapi` for parameters not declared on the annotation — see [Schema Harvesting](/docs/semantic-manifest/schema-harvesting) |

## Example Manifest

```json
{
  "version": "1.1.0",
  "generated_at": "2026-09-14T10:30:00.000Z",
  "source": { "url": "https://example.com", "paths": ["src"], "tool": "axag-cli", "tool_version": "1.0.2" },
  "conformance": "intermediate",
  "actions": [
    {
      "intent": "product.search",
      "entity": "product",
      "action_type": "read",
      "operation_id": "product_search",
      "description": "Search the product catalog",
      "required_parameters": [{ "name": "query", "type": "string" }],
      "optional_parameters": [{ "name": "category", "type": "string" }],
      "risk_level": "none",
      "idempotent": true,
      "scope": "public",
      "source_file": "src/search.html",
      "source_line": 12
    }
  ]
}
```

## Tool Mapping Rules Reference

Source: https://axag.org/docs/reference/tool-mapping-rules

Complete reference for mapping AXAG Semantic Manifest actions to MCP tool definitions.

## Mapping Table

| Manifest Field | MCP Tool Field | Transformation |
|---------------|---------------|----------------|
| `intent` | `name` | Replace `.` with `_` |
| `description` | `description` | Direct copy |
| `required_parameters[]` | `input_schema.properties` + `input_schema.required` | One property per parameter; names collected into `required` |
| `optional_parameters[]` | `input_schema.properties` | One property per parameter |
| `parameter.min` / `max` | `properties[x].minimum` / `maximum` | Renamed to JSON Schema keywords |
| `parameter.format` | `properties[x].format` | `url` → `uri`, `datetime` → `date-time`; others copied |
| `parameter.type`, `enum`, `minLength`, `maxLength`, `pattern`, `default`, `items`, `properties`, `description` | Same name | Direct copy |
| `action_type` | `metadata.action_type` | Direct copy |
| `risk_level` | `metadata.risk_level` | Direct copy, `none` when absent |
| `idempotent` | `metadata.idempotent` | Direct copy, `false` when absent |
| `confirmation_required` | `metadata.confirmation_required` | Direct copy, `false` when absent |
| `approval_required` | `metadata.approval_required` | Direct copy, `false` when absent |
| `approval_roles`, `async`, `scope`, `tenant_boundary`, `required_roles`, `side_effects`, `preconditions`, `postconditions` | `metadata.*` | Copied when present and non-empty |
| `intent`, `entity` | `metadata.source_intent`, `metadata.source_entity` | Direct copy |

## Tool Name Generation

```
name = intent.replaceAll(".", "_")
```

Examples:
- `product.search` → `product_search`
- `cart.add_item` → `cart_add_item`
- `checkout.begin` → `checkout_begin`

## Input Schema Generation

### Manifest parameters
```json
{
  "required_parameters": [{ "name": "query", "type": "string" }],
  "optional_parameters": [{ "name": "price_max", "type": "number", "min": 0 }]
}
```

### Generated JSON Schema
```json
{
  "type": "object",
  "properties": {
    "query": { "type": "string" },
    "price_max": { "type": "number", "minimum": 0 }
  },
  "required": ["query"]
}
```

## Metadata Generation

Safety and scope fields are grouped into `metadata` on the tool:

```json
{
  "metadata": {
    "action_type": "write",
    "risk_level": "high",
    "idempotent": false,
    "confirmation_required": true,
    "approval_required": false,
    "preconditions": ["cart_validated"],
    "side_effects": ["inventory_locked"],
    "source_intent": "checkout.begin",
    "source_entity": "order"
  }
}
```

## Nested Object Handling

`properties` on an `object` parameter is JSON Schema and is copied into the tool unchanged, including any nested `required` list:

### Manifest
```json
{
  "required_parameters": [
    {
      "name": "budget",
      "type": "object",
      "properties": {
        "amount": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "enum": ["USD", "EUR"] }
      }
    }
  ]
}
```

### Generated
```json
{
  "budget": {
    "type": "object",
    "properties": {
      "amount": { "type": "number", "minimum": 0 },
      "currency": { "type": "string", "enum": ["USD", "EUR"] }
    }
  }
}
```

## Array Handling

`items` on an `array` parameter is copied the same way:

### Manifest
```json
{ "optional_parameters": [{ "name": "tags", "type": "array", "items": { "type": "string" } }] }
```

### Generated
```json
{ "tags": { "type": "array", "items": { "type": "string" } } }
```

## Registry

`generateToolRegistry` wraps the tools with `schema_version`, `generated_at` and `source_manifest`. See [Tool Registry Generation](/docs/tool-generation/tool-registry-generation).

## Glossary

Source: https://axag.org/docs/reference/glossary

Canonical definitions of terms used throughout the AXAG specification.

## A

**Action** — A discrete operation that an agent can perform on an entity. Defined by an intent, entity, and action type.

**Action Type** — Classification of an action as `read`, `write`, or `delete`.

**Affordance** — A property of an interface element that communicates what actions are possible. In AXAG, affordances are declared via `axag-*` attributes rather than visual cues.

**Agent** — An AI system that performs tasks autonomously on behalf of a user by interpreting semantic contracts and invoking tools.

**Agent Experience (AX)** — The discipline of designing interfaces and systems that are optimized for autonomous agent consumption, distinct from User Experience (UX).

**Annotation** — An `axag-*` HTML attribute added to a UI element to declare its semantic intent, parameters, and constraints.

**Approval** — A gate that requires authorization from a designated role before an action can execute. Stronger than confirmation.

**AXAG** — Agent Experience Accessibility Guidelines. The specification that defines how to annotate web interfaces for agent consumption.

## C

**Confirmation** — A gate that requires explicit user acknowledgment before a high-risk action executes.

**Conformance Level** — A tier of AXAG compliance: Basic (required fields), Intermediate (parameters + safety), Full (all metadata).

**Constraint** — A validation rule on a parameter (type, range, enum, format, pattern).

## D

**Determinism** — The property that an action produces predictable, consistent results given the same inputs and preconditions.

## E

**Entity** — A domain object that actions operate on (e.g., product, cart, user, ticket).

## I

**Idempotent** — An operation that produces the same result when called multiple times with the same parameters.

**Intent** — The canonical identifier for an action, following the `entity.action` pattern (e.g., `product.search`).

## M

**Manifest** — See Semantic Manifest.

**MCP** — Model Context Protocol. A standard for AI agent tool integration. AXAG-generated tools target MCP format.

## P

**Postcondition** — A condition guaranteed to be true after successful execution of an action.

**Precondition** — A condition that MUST be true before an action can execute.

## R

**Risk Level** — Classification of an action's potential impact: `none`, `low`, `medium`, `high`, `critical`.

## S

**Safety Boundary** — The set of constraints (confirmation, approval, scope, tenant boundary) that protect against unintended agent actions.

**Scope** — The data access boundary for an action: `public`, `user`, `tenant`, `global`.

**Semantic Contract** — The machine-readable agreement between a UI and its agent consumers, defined by AXAG annotations and the Semantic Manifest.

**Semantic Manifest** — A JSON document that aggregates all AXAG annotations from a site into a discoverable, machine-readable contract.

**Side Effect** — An external consequence of executing an action (e.g., email sent, payment processed, inventory updated).

## T

**Tenant Boundary** — The isolation enforcement level for multi-tenant operations: `strict` (no cross-tenant access) or `relaxed`.

**Tool** — A callable function generated from a Semantic Manifest action, consumable by AI agents via MCP or similar protocols.

**Tool Generation** — The process of converting Semantic Manifest actions into MCP-compatible tool definitions.

## Term Disambiguation

Source: https://axag.org/docs/reference/term-disambiguation

Some terms in the AXAG ecosystem overlap with terms from related fields. This page clarifies the specific AXAG meaning.

## Action vs. Event

| Term | AXAG Meaning | Common Meaning |
|------|-------------|----------------|
| **Action** | An agent-invocable operation declared with `axag-intent` | Any user interaction (click, scroll, type) |

In AXAG, "action" specifically means a declared, tool-generatable operation — not every user interaction.

## Annotation vs. Attribute

| Term | AXAG Meaning | HTML Meaning |
|------|-------------|--------------|
| **Annotation** | The complete set of `axag-*` attributes on an element | Any HTML attribute |
| **Attribute** | A single `axag-*` key-value pair | A single HTML attribute |

An annotation is composed of multiple attributes. An element with `axag-intent`, `axag-entity`, and `axag-action-type` has one annotation consisting of three attributes.

## Intent vs. Event vs. Command

| Term | Meaning in AXAG | Similar Concepts |
|------|----------------|------------------|
| **Intent** | What the action is meant to accomplish (`product.search`) | REST endpoint, RPC method name |
| **Event** | Not an AXAG concept | DOM events, webhooks, pub/sub messages |
| **Command** | Not an AXAG concept | CQRS commands, CLI commands |

AXAG uses "intent" to emphasize that the annotation describes *purpose*, not *mechanism*.

## Manifest vs. Schema vs. Spec

| Term | AXAG Meaning |
|------|-------------|
| **Semantic Manifest** | The JSON document containing all actions for a site |
| **Schema** | The JSON Schema definition that validates a manifest |
| **Specification** | The AXAG standard itself (this documentation) |

## Confirmation vs. Approval

| Term | What It Is | When Required | Who Decides |
|------|-----------|---------------|-------------|
| **Confirmation** | User acknowledges the action | `risk_level >= high` | The user themselves |
| **Approval** | Authorized role authorizes the action | Business rule | A designated approver role |

Confirmation is "Are you sure?" — the user agrees.  
Approval is "Is this authorized?" — a privileged role agrees.

An action can require both: the user confirms, then a super_admin approves.

## Scope vs. Tenant Boundary

| Term | What It Defines |
|------|----------------|
| **Scope** | What data the action can access (`public`, `user`, `tenant`, `global`) |
| **Tenant Boundary** | How strictly tenant isolation is enforced (`strict`, `relaxed`) |

Scope declares the *access level*. Tenant boundary declares the *enforcement level*.

## Idempotent vs. Safe

| Term | Meaning |
|------|---------|
| **Idempotent** | Calling twice produces the same result (but may have side-effects the first time) |
| **Safe (read-only)** | Has no side-effects at all |

All read actions are safe AND idempotent.  
Some write actions are idempotent but NOT safe (e.g., `PUT` that updates a record).

## Risk Level vs. Action Type

Risk level and action type are orthogonal:

| | `read` | `write` | `delete` |
|--|--------|---------|----------|
| `none` | ✅ Common | Rare | Never |
| `low` | Possible | ✅ Common | Rare |
| `medium` | Possible | ✅ Common | Possible |
| `high` | Rare | ✅ Common | ✅ Common |
| `critical` | Rare | ✅ Common | Possible |


# Tutorials

## Tutorial: Add AXAG to a Page

Source: https://axag.org/docs/tutorials/add-axag-to-page

This step-by-step tutorial walks you through adding AXAG annotations to an existing web page.

## Prerequisites
- An existing HTML page with interactive elements
- Basic understanding of HTML attributes
- Familiarity with the [annotation attributes reference](/docs/reference/annotation-attributes)

## Step 1: Identify Annotatable Elements

Scan your page for elements that represent **agent-actionable operations**:
- Buttons that trigger actions (search, submit, delete)
- Links that perform state changes (not navigation links)
- Forms that submit data

**Not annotatable**: decorative elements, layout containers, navigation links to other pages.

## Step 2: Add Required Attributes

For each identified element, add the three required attributes:

```html
<!-- Before -->
<button onclick="searchProducts()">Search</button>

<!-- After -->
<button
  onclick="searchProducts()"
  <!-- axag-highlight-start -->
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  <!-- axag-highlight-end -->
>Search</button>
```

## Step 3: Add Parameters

Declare what inputs the action accepts:

```html
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  <!-- axag-highlight-start -->
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category","price_min","price_max"]'
  <!-- axag-highlight-end -->
>Search</button>
```

## Step 4: Add Description

```html
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category","price_min","price_max"]'
  <!-- axag-highlight-next-line -->
  axag-description="Search the product catalog with text query and optional filters"
>Search</button>
```

## Step 5: Add Safety Metadata

For write/delete operations, add risk level and idempotency:

```html
<button
  axag-intent="cart.add_item"
  axag-entity="cart"
  axag-action-type="write"
  axag-required-parameters='["product_id","quantity"]'
  <!-- axag-highlight-start -->
  axag-risk-level="low"
  axag-idempotent="false"
  <!-- axag-highlight-end -->
  axag-description="Add a product to the shopping cart"
>Add to Cart</button>
```

## Step 6: Add Preconditions and Postconditions

For operations with prerequisites or guaranteed outcomes:

```html
<button
  axag-intent="cart.begin_checkout"
  axag-entity="cart"
  axag-action-type="write"
  axag-required-parameters='["cart_id"]'
  <!-- axag-highlight-start -->
  axag-preconditions='["cart must have at least one item"]'
  axag-postconditions='["checkout session created"]'
  <!-- axag-highlight-end -->
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-description="Begin the checkout process"
>Checkout</button>
```

## Step 7: Validate

Run the AXAG validator to check your annotations:

```bash title="Validate annotations"
npx axag-lint src/my-page.html
```

## Complete Example

```html title="product-catalog.html" showLineNumbers
<!DOCTYPE html>
<html>
<body>
  <h1>Product Catalog</h1>

  <button
    axag-intent="product.search"
    axag-entity="product"
    axag-action-type="read"
    axag-required-parameters='["query"]'
    axag-optional-parameters='["category","sort_by"]'
    axag-risk-level="none"
    axag-idempotent="true"
    axag-description="Search products"
  >Search</button>

  <button
    axag-intent="cart.add_item"
    axag-entity="cart"
    axag-action-type="write"
    axag-required-parameters='["product_id","quantity"]'
    axag-risk-level="low"
    axag-idempotent="false"
    axag-description="Add item to cart"
  >Add to Cart</button>

  <button
    axag-intent="account.delete"
    axag-entity="account"
    axag-action-type="delete"
    axag-required-parameters='["account_id"]'
    axag-preconditions='["user must confirm deletion"]'
    axag-risk-level="critical"
    axag-confirmation-required="true"
    axag-idempotent="true"
    axag-description="Permanently delete the user account"
  >Delete Account</button>
</body>
</html>
```

## Next Steps
- [Generate a Semantic Manifest](/docs/tutorials/generate-semantic-manifest) from your annotations
- [Generate MCP Tools](/docs/tutorials/generate-mcp-tools) from the manifest

## Tutorial: Convert Scraping to Semantic

Source: https://axag.org/docs/tutorials/convert-scraping-to-semantic

This tutorial shows how to replace a **brittle scraping-based** agent integration with **AXAG semantic annotations** — making your agent integrations reliable, typed, and safe.

:::tip Why does this matter?
Every time a website redesigns, scraping agents break. AXAG annotations let agents discover operations through a **stable semantic contract** instead of fragile CSS selectors.
:::

---

## Interactive Comparison

Use the tabs below to explore the difference between scraping and the AXAG semantic approach. Toggle between views, check off migration steps, and explore the full pipeline.

Search</button>

<!-- Agent calls the generated MCP tool: -->
<!-- mcp.call("product_search", {query: "..."}) -->
<!-- → Structured JSON result, no parsing -->`}
  afterLang="html"
  afterTitle="✅ After — AXAG Semantic"
  comparisons={[
    { label: 'Reliability', before: 'Breaks on redesign', after: 'Stable across redesigns', icon: '🛡️' },
    { label: 'Type Safety', before: 'No', after: 'Yes (JSON Schema)', icon: '🔒' },
    { label: 'Parameter Discovery', before: 'Reverse-engineer DOM', after: 'Declared in manifest', icon: '🔍' },
    { label: 'Risk Awareness', before: 'None', after: 'Declared risk levels', icon: '⚠️' },
    { label: 'Idempotency', before: 'Unknown', after: 'Declared per-action', icon: '🔄' },
    { label: 'Maintenance', before: 'Per-site, per-redesign', after: 'Zero (site owner maintains)', icon: '🔧' },
    { label: 'Speed', before: 'Slow (parse full HTML)', after: 'Fast (direct tool call)', icon: '⚡' },
    { label: 'Error Handling', before: 'Catch DOM exceptions', after: 'Structured error codes', icon: '🚨' },
  ]}
  metrics={[
    { label: 'Reliability', before: '~40%', after: '99.9%', improvement: '↑ 150% more reliable', icon: '🛡️' },
    { label: 'Setup Time', before: '2-4 hrs', after: '15 min', improvement: '↓ 90% faster', icon: '⏱️' },
    { label: 'Maintenance', before: 'Weekly', after: 'Zero', improvement: '↓ 100% eliminated', icon: '🔧' },
    { label: 'Code Lines', before: '200+', after: '10', improvement: '↓ 95% less code', icon: '📄' },
  ]}
  pipeline={[
    {
      step: 1,
      title: 'Annotate the HTML',
      description: 'Add axag-* attributes to interactive elements in your source HTML.',
      icon: '🏷️',
      code: '<button axag-intent="product.search" ...>',
      lang: 'html',
    },
    {
      step: 2,
      title: 'Generate Semantic Manifest',
      description: 'Run the CLI to extract annotations into a structured JSON manifest.',
      icon: '📋',
      code: 'npx axag generate src --manifest axag-manifest.json',
      lang: 'bash',
    },
    {
      step: 3,
      title: 'Generate MCP Tools',
      description: 'Auto-generate typed tool definitions from the manifest.',
      icon: '🔧',
      code: 'npx axag generate-tools --manifest axag-manifest.json --output tools/',
      lang: 'bash',
    },
    {
      step: 4,
      title: 'Agent Calls Tools',
      description: 'Agents invoke structured MCP tools instead of scraping HTML.',
      icon: '🤖',
      code: 'result = mcp.call("product_search", {"query": "shoes"})',
      lang: 'python',
    },
  ]}
  checklist={[
    { text: 'Identify all scraping targets (pages, selectors)' },
    { text: 'Map each scraping target to an AXAG intent' },
    { text: 'Add axag-* annotations to source HTML' },
    { text: 'Generate semantic manifest' },
    { text: 'Generate MCP tools from manifest' },
    { text: 'Replace scraping code with tool calls' },
    { text: 'Remove BeautifulSoup / Selenium / Puppeteer dependencies' },
    { text: 'Add CI validation (npx axag-lint)' },
    { text: 'Run integration tests against generated tools' },
  ]}
/>

---

## Step-by-Step Walkthrough

### Step 1: The scraping approach (what we're replacing)

A typical scraping agent for a product search page:

```python title="❌ Fragile scraping approach" showLineNumbers
# ❌ Fragile scraping approach
from bs4 import BeautifulSoup

def search_products(query):
    response = requests.get(f"https://store.example.com/search?q={query}")
    soup = BeautifulSoup(response.text, 'html.parser')

    products = []
    for card in soup.select('.product-card'):  # Breaks if class changes
        name = card.select_one('.product-name').text  # Breaks if structure changes
        price_text = card.select_one('.price').text  # "$19.99" — needs parsing
        price = float(price_text.replace('$', '').replace(',', ''))
        products.append({'name': name, 'price': price})

    return products
```

**Problems with scraping**:
- CSS selectors break with every redesign
- Price parsing varies by locale
- Pagination requires DOM interaction
- No type safety or parameter validation
- No safety metadata (risk level, idempotency)

### Step 2: Annotate the search button

Add AXAG attributes to your existing HTML element — annotations are purely additive:

```html title="✅ Annotated search button" showLineNumbers
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category","price_min","price_max","sort_by","page"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Search the product catalog"
>Search</button>
```

### Step 3: Generate the Semantic Manifest

```bash title="Generate manifest from annotations"
npx axag generate src --manifest axag-manifest.json
```

### Step 4: Generate the MCP Tool

```bash title="Generate MCP tools from manifest"
npx axag generate-tools --manifest axag-manifest.json --output tools/
```

### Step 5: Agent uses the generated tool

```python title="✅ Semantic approach — structured tool call"
# ✅ Semantic approach — no scraping needed
def search_products(query, category=None, price_max=None):
    result = mcp_client.call_tool("product_search", {
        "query": query,
        "category": category,
        "price_max": price_max,
    })
    return result  # Structured JSON, no parsing needed
```

---

## Key Takeaway

> **Scraping is coupling to presentation. AXAG is coupling to intent.**
>
> When a site's CSS classes change, scraping agents break. When a site's *purpose* stays the same, AXAG agents keep working — because they're bound to semantic operations, not DOM structure.

## Tutorial: Generate a Semantic Manifest

Source: https://axag.org/docs/tutorials/generate-semantic-manifest

This tutorial walks through generating an AXAG Semantic Manifest from annotated HTML/JSX source files.

## Prerequisites
- Source files with AXAG annotations (see [Add AXAG to a Page](/docs/tutorials/add-axag-to-page))
- Node.js 18+

## Step 1: Install the CLI

```bash title="Install AXAG CLI"
npm install -D @web-axag/axag-cli
```

## Step 2: Scan Source Files

```bash title="Scan & generate manifest"
npx axag scan src/ --no-interactive --manifest axag-manifest.json --validate
```

The scanner:
1. Finds `.html`, `.htm`, `.jsx` and `.tsx` files (skipping `node_modules`, `dist`, `build`)
2. Reads every element that declares `axag-intent`
3. Builds one action per intent, sorted by intent, and warns about duplicates
4. Writes the manifest and, with `--validate`, checks it against the JSON Schema

## Step 3: Review the Generated Manifest

```json title="axag-manifest.json" showLineNumbers
{
  "version": "1.1.0",
  "generated_at": "2026-09-14T10:30:00.000Z",
  "source": { "paths": ["/app/src"], "tool": "axag-cli", "tool_version": "1.0.2" },
  "conformance": "intermediate",
  "actions": [
    {
      "intent": "product.search",
      "entity": "product",
      "action_type": "read",
      "operation_id": "product_search",
      "description": "Search the product catalog",
      "required_parameters": [{ "name": "query", "type": "string" }],
      "optional_parameters": [],
      "risk_level": "none",
      "idempotent": true,
      "source_file": "/app/src/SearchPage.tsx",
      "source_line": 14
    }
  ]
}
```

## Step 4: Check the Output

With `--validate`, the scan ends with:
```bash title="Validation output"
✔ Manifest written to /app/axag-manifest.json
  Actions: 12
  Conformance: intermediate
✔ Manifest passes schema validation ✅
```

Any `AXAG-CORE-*` warnings (invalid enum values, invalid JSON arrays, duplicate intents) are printed with the file and line to fix.

## Step 5: Or generate it from your bundler

An app with a bundler doesn't need a separate scan step. [`@axag/compiler`](/docs/tool-generation/build-time-compilation) reads the same sources on every build and writes the manifest into the output:

```ts title="vite.config.ts"

```

`axag scan` and `axag generate` stay useful for CI checks and for pages that aren't part of a bundled app.

## Step 6: Serve the Manifest

Make the manifest discoverable by agents:

### Option A: Well-Known URL
```http title="Well-known endpoint"
https://yoursite.com/.well-known/axag-manifest.json
```

### Option B: HTTP Header
```http title="HTTP Link header"
Link: </.well-known/axag-manifest.json>; rel="axag-manifest"
```

### Option C: HTML Meta Tag
```html title="HTML meta tag"
<meta name="axag-manifest" content="/.well-known/axag-manifest.json">
```

## Step 7: Automate in CI

```yaml title=".github/workflows/axag.yml" showLineNumbers
# .github/workflows/axag.yml
- name: Generate and validate manifest
  run: npx axag generate src --manifest axag-manifest.json --validate

- name: Deploy manifest
  run: cp axag-manifest.json public/.well-known/axag-manifest.json
```

## Next Steps
- [Generate MCP Tools](/docs/tutorials/generate-mcp-tools) from the manifest
- [Add Validation to CI](/docs/tutorials/add-validation-to-ci)

## Tutorial: Bind Zod or OpenAPI Schemas

Source: https://axag.org/docs/tutorials/bind-schemas

If your API already validates requests with Zod or describes them in OpenAPI, point AXAG at that definition instead of declaring parameters again. AXAG attributes then only carry intent and safety.

## Prerequisites
- `@web-axag/axag-cli` installed (see [Generate a Semantic Manifest](/docs/tutorials/generate-semantic-manifest))
- For Zod: `zod@4` in your project

## Option A: a Zod schema

```ts title="src/schemas/user.ts"

  .object({
    email: z.email().describe('Work email'),
    role: z.enum(['admin', 'member']).default('member'),
    seats: z.number().int().min(1).max(500),
  })
  .describe('Invite a user to the workspace');
```

Bind it on the element:

```html title="src/pages/team.html"
<form axag="write:user.invite!medium?idempotent=false" axag-schema="zod:./src/schemas/user.ts#InviteUser">
  <input name="email" type="email" aria-label="Email">
  <button type="submit">Invite</button>
</form>
```

Paths resolve from the directory of `axag.config.*`, or the current directory when there is none. TypeScript schema files are loaded directly; no build step is needed.

## Option B: an OpenAPI operation

```yaml title="openapi.yaml"
paths:
  /users/{userId}/deactivate:
    post:
      operationId: deactivateUser
      summary: Deactivate a user and revoke their sessions
      x-axag-risk-level: critical
      parameters:
        - { name: userId, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason: { type: string, enum: [offboarding, security, other] }
```

Bind it in config so the markup stays unchanged:

```json title="axag.config.json"
{
  "openapi": "./openapi.yaml",
  "bindings": {
    "user.deactivate": "openapi:deactivateUser"
  }
}
```

Path and query parameters and the `application/json` body are used; header and cookie parameters are not. Local `$ref`s and `allOf` are resolved.

## Generate the manifest

```bash
npx axag scan src --no-interactive --manifest axag-manifest.json --validate
```

```json title="axag-manifest.json — user.invite"
{
  "intent": "user.invite",
  "entity": "user",
  "action_type": "write",
  "operation_id": "user_invite",
  "description": "Invite a user to the workspace",
  "required_parameters": [
    { "name": "email", "type": "string", "format": "email", "description": "Work email", "source": "zod" },
    { "name": "seats", "type": "integer", "min": 1, "max": 500, "source": "zod" }
  ],
  "optional_parameters": [
    { "name": "role", "type": "string", "enum": ["admin", "member"], "default": "member", "source": "zod" }
  ],
  "risk_level": "medium",
  "idempotent": false
}
```

The schema's description was used because the annotation declares none. Zod's email `pattern` is also emitted and is left out here for brevity.

A binding that can't be loaded (missing file or export, unknown operation) is reported as an `AXAG-CORE-006` warning, and the action falls back to declared and harvested parameters.

## Keep the form and the schema in step

Lint with the generated manifest to catch drift between the form and the API:

```bash
npx axag-lint src --manifest axag-manifest.json
```

**AXAG-LINT-030** reports fields that are required in one and optional in the other, have different types, or allow different values.

## Next Steps
- [Schema Harvesting](/docs/semantic-manifest/schema-harvesting) — precedence rules in full
- [Generate MCP Tools](/docs/tutorials/generate-mcp-tools)

## Tutorial: Generate MCP Tools

Source: https://axag.org/docs/tutorials/generate-mcp-tools

This tutorial shows how to generate Model Context Protocol (MCP) tool definitions from an AXAG Semantic Manifest.

## Prerequisites
- A valid `axag-manifest.json` (see [Generate Semantic Manifest](/docs/tutorials/generate-semantic-manifest))
- Node.js 18+

## Step 1: Generate Tool Definitions

```bash title="Generate MCP tools from manifest"
npx axag generate-tools --manifest axag-manifest.json --output tools/
```

This writes a single registry file, `tools/tool-registry.json`, and prints each tool with its parameter count and risk level:

```bash title="Generated registry"
tools/
└── tool-registry.json   # { schema_version, generated_at, source_manifest, tools: [...] }
```

## Step 2: Review a Generated Tool

```json title="tools/tool-registry.json — tools[0]" showLineNumbers
{
  "name": "product_search",
  "description": "Search the product catalog",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "category": { "type": "string" },
      "price_min": { "type": "number", "minimum": 0 },
      "price_max": { "type": "number", "minimum": 0 }
    },
    "required": ["query"]
  },
  "metadata": {
    "action_type": "read",
    "risk_level": "none",
    "idempotent": true,
    "confirmation_required": false,
    "approval_required": false,
    "source_intent": "product.search",
    "source_entity": "product"
  }
}
```

## Step 3: Register Tools with MCP Server

The registry's `input_schema` is plain JSON Schema, so it can be served directly with the low-level MCP SDK server:

```typescript title="server.ts" showLineNumbers

const server = new Server(
  { name: "my-axag-server", version: "1.0.0" },
  { capabilities: { tools: {} } },
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: registry.tools.map((tool) => ({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.input_schema,
  })),
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  // Route to your API based on the tool name
  const result = await apiRouter.handle(request.params.name, request.params.arguments ?? {});
  return { content: [{ type: "text", text: JSON.stringify(result) }] };
});

await server.connect(new StdioServerTransport());
```

## Step 4: Test with an Agent

```typescript title="agent-client.ts"
// Agent discovers and uses the tool
const { tools } = await client.listTools();
const searchTool = tools.find((t) => t.name === "product_search");

const result = await client.callTool({
  name: "product_search",
  arguments: { query: "wireless headphones", price_max: 100 },
});

console.log(result.content); // Structured product data
```

## Step 5: Safety-Aware Execution

Safety fields live in each tool's `metadata`. Check them before dispatching a call:

```typescript title="safe-execution.ts" showLineNumbers
async function safeToolCall(name, args) {
  const tool = registry.tools.find((t) => t.name === name);

  // Check confirmation requirement
  if (tool.metadata.confirmation_required) {
    const confirmed = await promptUser(
      `This action requires confirmation: ${tool.description}. Proceed?`
    );
    if (!confirmed) return { error: "User declined confirmation" };
  }

  // Check approval requirement
  if (tool.metadata.approval_required) {
    const approval = await requestApproval(tool.metadata.approval_roles ?? []);
    if (!approval) return { error: "Approval not granted" };
  }

  return await client.callTool({ name, arguments: args });
}
```

:::warning
Client-side checks only guide a cooperative agent. Enforce confirmation, approval and tenant boundaries on the server as well.
:::

## Next Steps
- [Add Validation to CI](/docs/tutorials/add-validation-to-ci)
- Review the [Tool Mapping Rules Reference](/docs/reference/tool-mapping-rules)

## Tutorial: Add Validation to CI

Source: https://axag.org/docs/tutorials/add-validation-to-ci

This tutorial shows how to integrate AXAG validation into your CI/CD pipeline to catch annotation errors before deployment.

## Step 1: Install Dependencies

```bash title="Install AXAG dev dependencies"
npm install -D @web-axag/axag-cli @web-axag/axag-lint
```

## Step 2: Create Lint Configuration

Create `.axaglintrc.json`. Every rule has a default severity, so list only the ones you want to change:

```json title=".axaglintrc.json" showLineNumbers
{
  "include": ["**/*.{html,htm,jsx,tsx,vue}"],
  "exclude": ["node_modules/**", "dist/**", "**/*.test.*", "**/*.spec.*"],
  "manifestPath": "./axag-manifest.json",
  "rules": {
    "AXAG-LINT-032": "warning"
  }
}
```

`npx axag-lint --init` writes the file with every rule at its default.

## Step 3: Add npm Scripts

```json title="package.json — AXAG scripts"
{
  "scripts": {
    "axag:generate": "axag generate src --manifest axag-manifest.json --validate",
    "axag:lint": "axag-lint src --manifest axag-manifest.json",
    "axag:check": "npm run axag:generate && npm run axag:lint"
  }
}
```

`axag generate` compiles the manifest from your sources and `--validate` checks it against the JSON Schema. Generating the manifest first means the cross-reference rules have something current to compare with.

An app with a bundler can skip the generate step: [`@axag/compiler`](/docs/tool-generation/build-time-compilation) writes the manifest on every build.

## Step 4: GitHub Actions Workflow

Create `.github/workflows/axag-validation.yml`:

```yaml title=".github/workflows/axag-validation.yml" showLineNumbers
name: AXAG Validation

on:
  pull_request:
    paths:
      - 'src/**'
      - 'axag-manifest.json'
      - '.axaglintrc.json'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Generate and validate the manifest
        run: npm run axag:generate

      - name: Lint annotations
        run: npx axag-lint src --manifest axag-manifest.json --format github

      - name: Upload manifest artifact
        uses: actions/upload-artifact@v4
        with:
          name: axag-manifest
          path: axag-manifest.json
```

`--format github` turns findings into annotations on the pull request, at the file and line they came from.

## Step 5: Add Pre-Commit Hook

```bash title=".husky/pre-commit"
git diff --cached --name-only --diff-filter=ACM \
  | grep -E '\.(html|htm|jsx|tsx|vue)$' \
  | xargs -r npx axag-lint
```

## Step 6: Add Status Badge

```markdown title="README.md badge"
![AXAG Validation](https://github.com/your-org/your-repo/actions/workflows/axag-validation.yml/badge.svg)
```

## Troubleshooting

### CI fails with AXAG-LINT-010 (Intent not found in manifest)

The manifest is out of date. Regenerate it with `npm run axag:generate`, and generate it before linting in CI.

### CI fails on the conformance level you target

The manifest's `conformance` field is computed from what the annotations actually declare, so it drops when an action is missing risk, scope or idempotency. To fail the build on annotations below a level:

```bash title="Check annotations against a conformance level"
npx axag validate src --level intermediate --strict
```

### Lint reports AXAG-LINT-033 for a component action

`axag={spec}` is read at build time only when the spec is a module-level `const` or a `defineAction({...})` call. A spec built from props is registered at runtime and can't be in the manifest.

## Tutorial: Incremental Rollout

Source: https://axag.org/docs/tutorials/incremental-rollout

This tutorial shows how to adopt AXAG incrementally — starting with a single page and scaling to your entire application.

## Phase 1: Single Page Pilot (Week 1)

### Choose a pilot page
Pick a page with 2–5 interactive elements, ideally with a mix of read and write operations. Good candidates:
- A search page (read-only, low risk)
- A settings page (read + write, medium risk)

### Annotate
```html title="Pilot page — read + write annotations" showLineNumbers
<!-- Search (read) -->
<button axag-intent="product.search" axag-entity="product" axag-action-type="read"
  axag-required-parameters='["query"]' axag-risk-level="none" axag-idempotent="true"
  axag-description="Search products">Search</button>

<!-- Update settings (write) -->
<button axag-intent="settings.update" axag-entity="settings" axag-action-type="write"
  axag-required-parameters='["setting_key","setting_value"]' axag-risk-level="low"
  axag-idempotent="true" axag-description="Update a setting">Save</button>
```

### Generate and test
```bash title="Generate manifest & tools from pilot page"
npx axag scan --input src/pages/pilot/ --output axag-manifest.json
npx axag generate-tools --manifest axag-manifest.json --output tools/
```

### Success criteria
- [ ] Annotations pass validation
- [ ] Manifest generates without errors
- [ ] An agent can discover and call the tools

## Phase 2: Core Flows (Weeks 2–4)

Expand to all customer-facing user flows:

### Priority order
1. **Read operations** (search, list, view) — lowest risk
2. **Create operations** (new record) — low risk
3. **Update operations** (edit record) — medium risk
4. **Delete operations** (remove, cancel) — high risk
5. **Financial operations** (billing, payments) — critical risk

### Add CI validation
```bash title="Add linting to CI"
npm install -D @web-axag/axag-lint
# Add the GitHub Actions workflow from the Add Validation to CI tutorial
```

### Success criteria
- [ ] All user-facing actions annotated
- [ ] CI validation passing on every PR
- [ ] Intermediate conformance level achieved

## Phase 3: Full Coverage (Months 2–3)

### Annotate admin and internal flows
- Admin dashboards
- Approval workflows
- Tenant management

### Add safety metadata
- Preconditions and postconditions for all write operations
- Side-effects for operations with external consequences
- Tenant boundary declarations for multi-tenant operations

### Target full conformance
```bash title="Target full conformance"
npx axag validate src --level full --strict
```

The manifest's own `conformance` field is computed from what the annotations declare, so `axag generate --validate` shows where you have reached.

### Success criteria
- [ ] 100% of actionable elements annotated
- [ ] Full conformance level achieved
- [ ] Runtime validation enforcing contracts

## Phase 4: Optimization (Ongoing)

- Monitor agent success rates
- Refine parameter schemas based on agent usage patterns
- Contribute domain-specific patterns back to the AXAG community
- Track annotation coverage metrics

## Rollout Metrics Dashboard

| Metric | Phase 1 | Phase 2 | Phase 3 | Phase 4 |
|--------|---------|---------|---------|---------|
| Annotated actions | 2–5 | 20–50 | 100% | 100% |
| Conformance level | Basic | Intermediate | Full | Full |
| CI validation | No | Yes | Yes | Yes |
| Runtime validation | No | No | Yes | Yes |
| Agent frameworks supported | 1 | 1–2 | All | All |

## Tutorial: Cross-Domain Agent Workflow

Source: https://axag.org/docs/tutorials/cross-domain-example

This tutorial demonstrates an agent performing a multi-step workflow that spans multiple AXAG-annotated domains — from CRM lead creation to marketing campaign targeting.

## Scenario

An AI agent assists a sales rep with:
1. Creating a lead in the CRM
2. Searching for similar companies in the product catalog
3. Adding the lead to a marketing audience segment
4. Scheduling a follow-up campaign

## Step 1: Create a Lead (CRM Domain)

```typescript title="Step 1 — Create Lead (CRM domain)"
// Agent calls the CRM tool
const lead = await mcpClient.callTool("lead_create", {
  first_name: "Jane",
  last_name: "Smith",
  email: "jane.smith@acme.com",
  company: "Acme Corp",
  source: "referral",
});
// Returns: { lead_id: "lead_abc123", status: "created" }
```

## Step 2: Search for Similar Companies (E-Commerce Domain)

```typescript title="Step 2 — Product Search (E-Commerce domain)"
// Agent uses product search to find relevant products for this lead's industry
const products = await mcpClient.callTool("product_search", {
  query: "enterprise software",
  category: "B2B",
  sort_by: "relevance",
});
```

## Step 3: Add to Audience Segment (Marketing Domain)

```typescript title="Step 3 — Create Audience Segment (Marketing domain)"
// Agent adds the lead to a targeted segment
const segment = await mcpClient.callTool("audience_create_segment", {
  name: "Enterprise Referrals Q1",
  rules: {
    operator: "AND",
    conditions: [
      { field: "source", operator: "equals", value: "referral" },
      { field: "company_size", operator: "gt", value: 100 },
    ],
  },
});
```

## Step 4: Schedule Campaign (Marketing Domain)

```typescript title="Step 4 — Schedule Campaign ⚠️ requires confirmation" showLineNumbers
// This requires confirmation due to high risk
const campaign = await mcpClient.callTool("campaign_create", {
  name: "Enterprise Referral Welcome",
  channel: "email",
  audience_segment_id: segment.segment_id,
  budget: { amount: 500, currency: "USD" },
});

// Schedule — requires user confirmation
const confirmation = await promptUser(
  "Schedule campaign 'Enterprise Referral Welcome' to send tomorrow at 9 AM EST?"
);

if (confirmation) {
  await mcpClient.callTool("campaign_schedule", {
    campaign_id: campaign.campaign_id,
    send_at: "2024-02-15T09:00:00-05:00",
    timezone: "America/New_York",
  });
}
```

## Safety Gates in Action

Notice how the AXAG safety metadata guided the agent:

| Step | Tool | Risk | Confirmation | Why |
|------|------|------|-------------|-----|
| 1 | `lead_create` | Low | No | Creating a lead is low-impact |
| 2 | `product_search` | None | No | Read-only operation |
| 3 | `audience_create_segment` | None | No | Metadata creation, no external impact |
| 4a | `campaign_create` | Low | No | Creates in draft status |
| 4b | `campaign_schedule` | High | **Yes** | Triggers message delivery |

The agent knew to ask for confirmation only at the scheduling step because the AXAG manifest declared `campaign_schedule` as high risk with `confirmation_required: true`.

## Key Takeaways

1. **Cross-domain workflows are seamless** when each domain uses AXAG
2. **Safety metadata prevents autonomous dangerous actions** — the agent paused at the right moment
3. **No scraping needed** — every step used structured tool calls
4. **Tool discovery is automatic** — the agent found tools via the manifest without hardcoding


# Examples

## Examples Overview

Source: https://axag.org/docs/examples/overview

This section provides practical, copy-paste-ready examples of AXAG annotations, manifests, and generated tools across various patterns.

## What's in This Section

| Page | Description |
|------|-------------|
| [Before & After](/docs/examples/before-and-after) | Side-by-side comparison of un-annotated vs. AXAG-annotated UI |
| [Anti-Patterns](/docs/examples/anti-patterns) | Common mistakes and how to avoid them |
| [Copy-Paste Snippets](/docs/examples/copy-paste-snippets) | Ready-to-use annotation templates |
| [Domain Gallery](/docs/examples/domain-gallery) | Complete annotation sets for common domains |

## Quick Start Examples

### Minimal Read Action
```html
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-required-parameters='["query"]'
  axag-description="Search products"
>Search</button>
```

### Minimal Write Action
```html
<button
  axag-intent="lead.create"
  axag-entity="lead"
  axag-action-type="write"
  axag-required-parameters='["email","name"]'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-description="Create a new lead"
>Create Lead</button>
```

### Full Safety-Annotated Action
```html
<button
  axag-intent="account.delete"
  axag-entity="account"
  axag-action-type="delete"
  axag-required-parameters='["account_id"]'
  axag-preconditions='["user must confirm deletion","no pending transactions"]'
  axag-postconditions='["account deactivated","data scheduled for deletion in 30 days"]'
  axag-risk-level="critical"
  axag-confirmation-required="true"
  axag-approval-required="true"
  axag-approval-roles='["super_admin"]'
  axag-idempotent="true"
  axag-side-effects='["data_deletion_scheduled","session_invalidation","notification_email"]'
  axag-scope="tenant"
  axag-description="Permanently delete a user account"
>Delete Account</button>
```

## Before & After Examples

Source: https://axag.org/docs/examples/before-and-after

These examples show the transformation from un-annotated HTML to AXAG-annotated HTML.

## Example 1: Search Button

  Search
</button>`}
  after={`<button onclick="search()"
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category","sort_by"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Search the product catalog"
>Search</button>`}
/>

**What changed**: The button now declares its semantic purpose, parameters, and safety profile. An agent can discover and invoke this action without parsing the DOM.

## Example 2: Delete Button

  Delete User
</button>`}
  after={`<button class="btn btn-danger"
  onclick="deleteUser(userId)"
  axag-intent="user.delete"
  axag-entity="user"
  axag-action-type="delete"
  axag-required-parameters='["user_id"]'
  axag-preconditions='["user must not have active sessions"]'
  axag-postconditions='["user deactivated","sessions invalidated"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-scope="tenant"
  axag-description="Delete (deactivate) a user"
>Delete User</button>`}
/>

**What changed**: The destructive nature is now machine-readable. An agent knows it must confirm with the user, that active sessions are a precondition, and that the operation is scoped to the current tenant.

## Example 3: Form Submit

  <input name="email" type="email" />
  <input name="name" type="text" />
  <button type="submit">
    Create Account
  </button>
</form>`}
  after={`<form onsubmit="submitForm()">
  <input name="email" type="email" />
  <input name="name" type="text" />
  <button type="submit"
    axag-intent="account.create"
    axag-entity="account"
    axag-action-type="write"
    axag-required-parameters='["email","name"]'
    axag-optional-parameters='["phone","company"]'
    axag-postconditions='["account created","welcome email sent"]'
    axag-risk-level="low"
    axag-idempotent="false"
    axag-side-effects='["welcome_email"]'
    axag-description="Create a new user account"
  >Create Account</button>
</form>`}
/>

**What changed**: The form's submit action is now semantically declared. An agent knows exactly what parameters to provide, what side-effects to expect, and that duplicate submissions create duplicate accounts.

## Example 4: Approval Button

  Approve
</button>`}
  after={`<button onclick="approve(reqId)"
  axag-intent="approval.approve"
  axag-entity="purchase_requisition"
  axag-action-type="write"
  axag-required-parameters='["requisition_id","approval_step_id"]'
  axag-optional-parameters='["comments"]'
  axag-preconditions='["caller must be designated approver"]'
  axag-postconditions='["step approved","next approver notified"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["workflow_advancement","notification"]'
  axag-scope="tenant"
  axag-description="Approve a purchase requisition"
>Approve</button>`}
/>

**What changed**: The approval action now declares the full workflow context — who can approve, what happens next, and that it's part of a multi-step process.

## Example 5: Async Export

  Export CSV
</button>`}
  after={`<button onclick="exportData()"
  axag-intent="dataset.export"
  axag-entity="dataset"
  axag-action-type="read"
  axag-required-parameters='["dataset_id"]'
  axag-optional-parameters='["columns","format","row_limit"]'
  axag-risk-level="none"
  axag-idempotent="false"
  axag-async="true"
  axag-scope="tenant"
  axag-description="Export dataset as downloadable file"
>Export CSV</button>`}
/>

**What changed**: The agent now knows this is an async operation — it will receive a job ID and should poll for completion rather than expecting immediate results.

## Anti-Patterns

Source: https://axag.org/docs/examples/anti-patterns

These are common mistakes when annotating with AXAG. Each anti-pattern shows what NOT to do and the correct approach.

## 1. Presentation-Coupled Intent

❌ **Wrong**: Intent describes HOW it looks, not WHAT it does
```html
<button axag-intent="red_button.click" axag-entity="red_button" axag-action-type="write">
  Delete
</button>
```

✅ **Correct**: Intent describes the semantic action
```html
<button axag-intent="account.delete" axag-entity="account" axag-action-type="delete">
  Delete
</button>
```

**Why**: Intents must be presentation-independent. "Red button click" is meaningless to an agent.

## 2. Missing Risk Level on Destructive Action

❌ **Wrong**: Delete with no risk metadata
```html
<button axag-intent="user.delete" axag-entity="user" axag-action-type="delete">
  Delete User
</button>
```

✅ **Correct**: Explicit risk level and confirmation
```html
<button axag-intent="user.delete" axag-entity="user" axag-action-type="delete"
  axag-risk-level="high" axag-confirmation-required="true" axag-idempotent="true">
  Delete User
</button>
```

**Why**: Without risk metadata, an agent may execute destructive actions without safeguards.

## 3. Overlapping Required and Optional Parameters

❌ **Wrong**: Same parameter in both lists
```html
<button axag-required-parameters='["email","name"]'
        axag-optional-parameters='["email","phone"]'>
```

✅ **Correct**: Each parameter in exactly one list
```html
<button axag-required-parameters='["email","name"]'
        axag-optional-parameters='["phone"]'>
```

**Why**: A parameter is either required or optional — never both.

## 4. Using camelCase in Intent Names

❌ **Wrong**: camelCase
```html
<button axag-intent="productSearch" axag-entity="product">
```

✅ **Correct**: `entity.action` with snake_case
```html
<button axag-intent="product.search" axag-entity="product">
```

**Why**: Intent naming convention is `entity.action` with snake_case for consistency and machine parsing.

## 5. Missing Idempotency Declaration

❌ **Wrong**: Write action with no idempotency information
```html
<button axag-intent="cart.add_item" axag-entity="cart" axag-action-type="write">
```

✅ **Correct**: Explicit idempotency
```html
<button axag-intent="cart.add_item" axag-entity="cart" axag-action-type="write"
  axag-idempotent="false">
```

**Why**: Agents need to know if retrying a failed operation is safe.

## 6. Annotating Non-Actionable Elements

❌ **Wrong**: Annotating a heading
```html
<h1 axag-intent="product.view" axag-entity="product" axag-action-type="read">
  Product Details
</h1>
```

✅ **Correct**: Only annotate actionable elements
```html
<h1>Product Details</h1>
<!-- Annotations go on buttons, links, or form submits -->
```

**Why**: Headings, labels, and display elements don't represent agent-invocable actions.

## 7. Hardcoded Entity IDs in Annotations

❌ **Wrong**: Embedding specific IDs
```html
<button axag-intent="order.track" axag-required-parameters='["order_12345"]'>
```

✅ **Correct**: Declaring parameter names, not values
```html
<button axag-intent="order.track" axag-required-parameters='["order_id"]'>
```

**Why**: Annotations declare the parameter schema, not instance data.

## 8. Approval Without Approval Roles

❌ **Wrong**: Approval required but no roles specified
```html
<button axag-intent="billing.change_plan" axag-approval-required="true">
```

✅ **Correct**: Approval with designated roles
```html
<button axag-intent="billing.change_plan" axag-approval-required="true"
  axag-approval-roles='["billing_admin","super_admin"]'>
```

**Why**: Without roles, the runtime can't validate who is authorized to approve.

## 9. Using `write` for Read-Only Operations

❌ **Wrong**: Search marked as write
```html
<button axag-intent="product.search" axag-action-type="write">
```

✅ **Correct**: Search is a read
```html
<button axag-intent="product.search" axag-action-type="read">
```

**Why**: Incorrect action types break safety analysis — writes trigger confirmation logic that reads don't need.

## 10. Ignoring Scope on Tenant-Sensitive Operations

❌ **Wrong**: Admin action with no scope
```html
<button axag-intent="admin.list_users" axag-entity="user" axag-action-type="read">
```

✅ **Correct**: Explicit tenant scope
```html
<button axag-intent="admin.list_users" axag-entity="user" axag-action-type="read"
  axag-scope="tenant" axag-tenant-boundary="strict">
```

**Why**: Without scope, agents may attempt cross-tenant access.

## 11. Vague or Missing Description

❌ **Wrong**: No description or generic description
```html
<button axag-intent="report.generate" axag-description="Click to do something">
```

✅ **Correct**: Specific, actionable description
```html
<button axag-intent="report.generate"
  axag-description="Generate an analytics report for the specified date range and metrics">
```

**Why**: Descriptions are used by agents to determine when to invoke a tool. Vague descriptions lead to incorrect tool selection.

## Copy-Paste Snippets

Source: https://axag.org/docs/examples/copy-paste-snippets

Ready-to-use annotation templates for common UI patterns. Copy, paste, and customize.

## Macro Shorthand

Every template below can also be written as a single [`axag` macro](/docs/specification/macro-syntax) (replace `entity` with your entity name); add longhand attributes for anything the macro can't express, such as descriptions:

```html title="⚡ Macro templates"
<button axag="read:entity.search!none?idempotent&req=query&opt=category,sort_by" axag-description="Search ENTITY_PLURAL">Search</button>
<button axag="write:entity.create!low?idempotent=false" axag-description="Create a ENTITY">Create</button>
<button axag="delete:entity.delete!high?confirm&idempotent&scope=tenant" axag-description="Delete a ENTITY">Delete</button>
```

## Read Operations

### Search
```html title="🔍 Search Operation Template"
<button
  <!-- axag-highlight-start -->
  axag-intent="ENTITY.search"
  axag-entity="ENTITY"
  axag-action-type="read"
  <!-- axag-highlight-end -->
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category","sort_by","page","page_size"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Search ENTITY_PLURAL"
>Search</button>
```

### List
```html title="📋 List Operation Template"
<button
  <!-- axag-highlight-start -->
  axag-intent="ENTITY.list"
  axag-entity="ENTITY"
  axag-action-type="read"
  <!-- axag-highlight-end -->
  axag-optional-parameters='["status","page","page_size","sort_by"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="List all ENTITY_PLURAL"
>View All</button>
```

### Get Details
```html title="🔎 Get Details Template"
<button
  <!-- axag-highlight-start -->
  axag-intent="ENTITY.get"
  axag-entity="ENTITY"
  axag-action-type="read"
  <!-- axag-highlight-end -->
  axag-required-parameters='["ENTITY_id"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Get details of a specific ENTITY"
>View Details</button>
```

## Write Operations

### Create
```html title="➕ Create Operation Template"
<button
  axag-intent="ENTITY.create"
  axag-entity="ENTITY"
  axag-action-type="write"
  axag-required-parameters='["REQUIRED_FIELDS"]'
  axag-optional-parameters='["OPTIONAL_FIELDS"]'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-side-effects='["SIDE_EFFECTS"]'
  axag-description="Create a new ENTITY"
>Create</button>
```

### Update
```html title="✏️ Update Operation Template"
<button
  axag-intent="ENTITY.update"
  axag-entity="ENTITY"
  axag-action-type="write"
  axag-required-parameters='["ENTITY_id"]'
  axag-optional-parameters='["UPDATABLE_FIELDS"]'
  axag-risk-level="medium"
  axag-idempotent="true"
  axag-confirmation-required="true"
  axag-description="Update an existing ENTITY"
>Save Changes</button>
```

## Delete Operations

### Soft Delete
```html title="🗑️ Soft Delete Template"
<button
  axag-intent="ENTITY.delete"
  axag-entity="ENTITY"
  axag-action-type="delete"
  axag-required-parameters='["ENTITY_id"]'
  axag-preconditions='["PRECONDITIONS"]'
  axag-postconditions='["ENTITY deactivated"]'
  <!-- axag-highlight-start -->
  axag-risk-level="high"
  axag-confirmation-required="true"
  <!-- axag-highlight-end -->
  axag-idempotent="true"
  axag-description="Delete (deactivate) a ENTITY"
>Delete</button>
```

### Hard Delete (Critical)
```html title="⚠️ Hard Delete Template — Critical Risk"
<button
  axag-intent="ENTITY.delete_permanent"
  axag-entity="ENTITY"
  axag-action-type="delete"
  axag-required-parameters='["ENTITY_id"]'
  axag-preconditions='["no dependent records"]'
  axag-postconditions='["ENTITY permanently removed"]'
  <!-- axag-highlight-start -->
  axag-risk-level="critical"
  axag-confirmation-required="true"
  axag-approval-required="true"
  axag-approval-roles='["admin"]'
  <!-- axag-highlight-end -->
  axag-idempotent="true"
  axag-description="Permanently delete a ENTITY"
>Permanently Delete</button>
```

## Approval Operations

### Submit for Approval
```html title="✅ Approval Workflow Template"
<button
  axag-intent="ENTITY.submit_for_approval"
  axag-entity="ENTITY"
  axag-action-type="write"
  axag-required-parameters='["ENTITY_id"]'
  axag-preconditions='["ENTITY must be in draft status"]'
  axag-postconditions='["ENTITY submitted","approver notified"]'
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["notification"]'
  axag-description="Submit ENTITY for approval"
>Submit for Approval</button>
```

## Async Operations

### Export
```html title="📤 Async Export Template"
<button
  axag-intent="ENTITY.export"
  axag-entity="ENTITY"
  axag-action-type="read"
  axag-required-parameters='["ENTITY_id"]'
  axag-optional-parameters='["format","columns"]'
  axag-risk-level="none"
  axag-idempotent="false"
  axag-async="true"
  axag-scope="tenant"
  axag-description="Export ENTITY data as a downloadable file"
>Export</button>
```

## How to Use These Templates

1. Copy the snippet
2. Replace `ENTITY` with your domain entity name (e.g., `product`, `user`, `ticket`)
3. Replace `ENTITY_PLURAL` with the plural form (e.g., `products`, `users`, `tickets`)
4. Replace `REQUIRED_FIELDS`, `OPTIONAL_FIELDS`, etc. with actual field names
5. Adjust risk levels and safety metadata based on your domain
6. Run `npx axag-lint` to validate

## Domain Gallery

Source: https://axag.org/docs/examples/domain-gallery

A visual gallery of AXAG-annotated UI patterns across industry domains. Each card shows the domain, the annotated element, and the resulting semantic manifest + MCP tool.

---

## 🛒 E-Commerce

### Product Search
```html
<input
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category","price_min","price_max","sort_by","page"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Search the product catalogue"
/>
```

**Manifest Intent:**
```json
{
  "intent": "product.search",
  "entity": "product",
  "action_type": "read",
  "operation_id": "product_search",
  "description": "Search the product catalogue",
  "required_parameters": [{ "name": "query", "type": "string" }],
  "optional_parameters": [
    { "name": "category", "type": "string" },
    { "name": "price_min", "type": "string" },
    { "name": "price_max", "type": "string" },
    { "name": "sort_by", "type": "string" },
    { "name": "page", "type": "string" }
  ]
}
```

**Generated MCP Tool:**
```json
{
  "name": "product_search",
  "description": "Search the product catalogue",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "category": { "type": "string" },
      "price_min": { "type": "number" },
      "price_max": { "type": "number" },
      "sort_by": { "type": "string", "enum": ["relevance","price_asc","price_desc","rating"] },
      "page": { "type": "integer", "minimum": 1 }
    },
    "required": ["query"]
  }
}
```

---

### Add to Cart
```html
<button
  axag-intent="cart.add_item"
  axag-entity="cart"
  axag-action-type="write"
  axag-required-parameters='["product_id","quantity"]'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-side-effects='["cart_updated"]'
  axag-description="Add a product to the shopping cart"
>Add to Cart</button>
```

---

### Place Order
```html
<button
  axag-intent="order.place"
  axag-entity="order"
  axag-action-type="write"
  axag-required-parameters='["cart_id","shipping_address_id","payment_method_id"]'
  axag-preconditions='["cart is not empty","payment method valid"]'
  axag-postconditions='["order created","payment charged","confirmation email sent"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-side-effects='["payment","email","inventory_update"]'
  axag-description="Place an order and process payment"
>Place Order</button>
```

---

## 📈 Marketing

### Create Campaign
```html
<button
  axag-intent="campaign.create"
  axag-entity="campaign"
  axag-action-type="write"
  axag-required-parameters='["name","channel","audience_segment_id","budget"]'
  axag-optional-parameters='["start_date","end_date","content_template_id"]'
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-side-effects='["campaign_draft_created"]'
  axag-description="Create a new marketing campaign"
>Create Campaign</button>
```

---

### Schedule Campaign
```html
<button
  axag-intent="campaign.schedule"
  axag-entity="campaign"
  axag-action-type="write"
  axag-required-parameters='["campaign_id","send_date"]'
  axag-preconditions='["campaign status is draft","audience assigned","content approved"]'
  axag-postconditions='["campaign scheduled","team notified"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-side-effects='["notification"]'
  axag-scope="tenant"
  axag-description="Schedule a campaign for delivery"
>Schedule</button>
```

---

## 🤝 CRM

### Create Lead
```html
<button
  axag-intent="lead.create"
  axag-entity="lead"
  axag-action-type="write"
  axag-required-parameters='["first_name","last_name","email","company"]'
  axag-optional-parameters='["phone","source","notes"]'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-side-effects='["lead_created","sales_rep_assigned"]'
  axag-description="Create a new sales lead"
>Add Lead</button>
```

---

### Progress Opportunity
```html
<button
  axag-intent="opportunity.advance_stage"
  axag-entity="opportunity"
  axag-action-type="write"
  axag-required-parameters='["opportunity_id","new_stage"]'
  axag-constraints='{"new_stage": {"enum": ["qualification","proposal","negotiation","closed_won","closed_lost"]}}'
  axag-preconditions='["opportunity exists","stage transition valid"]'
  axag-postconditions='["pipeline updated","forecast recalculated"]'
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-idempotent="true"
  axag-description="Move an opportunity to the next sales stage"
>Advance Stage</button>
```

---

## ✈️ Travel

### Search Flights
```html
<button
  axag-intent="flight.search"
  axag-entity="flight"
  axag-action-type="read"
  axag-required-parameters='["origin","destination","departure_date"]'
  axag-optional-parameters='["return_date","passengers","cabin_class","max_stops"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-description="Search for available flights"
>Search Flights</button>
```

---

### Book Flight
```html
<button
  axag-intent="booking.create"
  axag-entity="booking"
  axag-action-type="write"
  axag-required-parameters='["flight_id","passenger_details","payment_method_id"]'
  axag-preconditions='["seats available","passenger details valid","payment method valid"]'
  axag-postconditions='["booking confirmed","e-ticket issued","confirmation email sent"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-side-effects='["payment","email","seat_reservation"]'
  axag-description="Book a flight and issue tickets"
>Book Now</button>
```

---

## 💼 Jobs

### Apply for Job
```html
<button
  axag-intent="application.submit"
  axag-entity="application"
  axag-action-type="write"
  axag-required-parameters='["job_id","resume_id"]'
  axag-optional-parameters='["cover_letter","referral_code"]'
  axag-preconditions='["job posting is active","candidate has not already applied"]'
  axag-postconditions='["application submitted","recruiter notified","confirmation email sent"]'
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-side-effects='["notification","email"]'
  axag-description="Submit a job application"
>Apply</button>
```

---

## 📊 Analytics

### Generate Report
```html
<button
  axag-intent="report.generate"
  axag-entity="report"
  axag-action-type="read"
  axag-required-parameters='["report_type","date_range_start","date_range_end"]'
  axag-optional-parameters='["dimensions","metrics","filters","format"]'
  axag-risk-level="none"
  axag-idempotent="true"
  axag-async="true"
  axag-scope="tenant"
  axag-description="Generate an analytics report"
>Generate Report</button>
```

---

### Export Dataset
```html
<button
  axag-intent="dataset.export"
  axag-entity="dataset"
  axag-action-type="read"
  axag-required-parameters='["dataset_id","format"]'
  axag-constraints='{"format": {"enum": ["csv","json","parquet","xlsx"]}}'
  axag-risk-level="none"
  axag-idempotent="false"
  axag-async="true"
  axag-scope="tenant"
  axag-description="Export a dataset for download"
>Export</button>
```

---

## 🎫 Support

### Create Ticket
```html
<button
  axag-intent="ticket.create"
  axag-entity="ticket"
  axag-action-type="write"
  axag-required-parameters='["subject","description","priority"]'
  axag-optional-parameters='["category","attachments"]'
  axag-constraints='{"priority": {"enum": ["low","medium","high","critical"]}}'
  axag-risk-level="low"
  axag-idempotent="false"
  axag-side-effects='["ticket_created","support_team_notified"]'
  axag-description="Create a support ticket"
>Submit Ticket</button>
```

---

### Escalate Ticket
```html
<button
  axag-intent="ticket.escalate"
  axag-entity="ticket"
  axag-action-type="write"
  axag-required-parameters='["ticket_id","reason"]'
  axag-preconditions='["ticket status is open","not already escalated"]'
  axag-postconditions='["ticket priority raised","escalation manager notified"]'
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-approval-required="true"
  axag-approval-roles='["support_lead"]'
  axag-idempotent="true"
  axag-side-effects='["notification"]'
  axag-description="Escalate a support ticket to a higher tier"
>Escalate</button>
```

---

## 🏢 Enterprise

### Admin — Delete User
```html
<button
  axag-intent="user.delete"
  axag-entity="user"
  axag-action-type="delete"
  axag-required-parameters='["user_id"]'
  axag-preconditions='["user has no active sessions","all data backed up"]'
  axag-postconditions='["user deactivated","sessions revoked","audit log entry created"]'
  axag-risk-level="critical"
  axag-confirmation-required="true"
  axag-approval-required="true"
  axag-approval-roles='["superadmin"]'
  axag-idempotent="true"
  axag-required-roles='["admin"]'
  axag-scope="tenant"
  axag-description="Permanently delete a user account"
>Delete User</button>
```

---

### Multi-Step Approval
```html
<!-- Step 1: Submit Request -->
<button
  axag-intent="access_request.submit"
  axag-entity="access_request"
  axag-action-type="write"
  axag-required-parameters='["resource_id","access_level","justification"]'
  axag-postconditions='["request submitted","first approver notified"]'
  axag-risk-level="medium"
  axag-confirmation-required="true"
  axag-idempotent="false"
  axag-description="Submit an access request"
>Request Access</button>

<!-- Step 2: Manager Approve -->
<button
  axag-intent="access_request.approve_manager"
  axag-entity="access_request"
  axag-action-type="write"
  axag-required-parameters='["request_id","decision","comments"]'
  axag-constraints='{"decision": {"enum": ["approve","reject"]}}'
  axag-preconditions='["request status is pending_manager"]'
  axag-postconditions='["manager decision recorded","compliance reviewer notified"]'
  axag-risk-level="high"
  axag-required-roles='["manager"]'
  axag-approval-required="true"
  axag-approval-roles='["manager"]'
  axag-idempotent="true"
  axag-description="Manager reviews and approves or rejects an access request"
>Approve / Reject</button>

<!-- Step 3: Compliance Approve -->
<button
  axag-intent="access_request.approve_compliance"
  axag-entity="access_request"
  axag-action-type="write"
  axag-required-parameters='["request_id","decision","compliance_notes"]'
  axag-constraints='{"decision": {"enum": ["approve","reject"]}}'
  axag-preconditions='["request status is pending_compliance","manager approved"]'
  axag-postconditions='["access provisioned","audit trail updated"]'
  axag-risk-level="critical"
  axag-required-roles='["compliance_officer"]'
  axag-approval-required="true"
  axag-approval-roles='["compliance_officer"]'
  axag-idempotent="true"
  axag-description="Compliance officer reviews and finalises an access request"
>Final Approval</button>
```

---

## Quick Reference Matrix

| Domain | Entity | Intents | Risk Range | Approval Needed |
|--------|--------|---------|-----------|-----------------|
| E-Commerce | product, cart, order | search, add, place | none → high | Order placement |
| Marketing | campaign | create, schedule | medium → high | Scheduling |
| CRM | lead, opportunity | create, advance | low → medium | Stage changes |
| Travel | flight, booking | search, create | none → high | Booking |
| Jobs | application | submit | medium | Submission |
| Analytics | report, dataset | generate, export | none | — |
| Support | ticket | create, escalate | low → medium | Escalation |
| Enterprise | user, access_request | delete, submit, approve | medium → critical | Multi-step |

## Proposed Patterns vs Normative Rules

Source: https://axag.org/docs/examples/proposed-vs-normative

AXAG documentation distinguishes between **normative rules** (binding requirements) and **proposed patterns** (recommended approaches that are not yet part of the formal specification). This page clarifies the distinction with concrete examples.

## Content Classification

| Classification | Meaning | Language | Binding? |
|---------------|---------|----------|----------|
| **Normative** | Binding requirement. Implementations MUST comply. | MUST, MUST NOT, SHALL | Yes |
| **Recommended** | Best practice. Implementations SHOULD follow. | SHOULD, SHOULD NOT | Strongly advised |
| **Informative** | Explanatory context. Not binding. | — | No |
| **Example** | Illustrative code. Not binding. | — | No |
| **Proposed Pattern** | Inferred implementation approach. Not yet canonical. | — | No |

---

## Normative Rules

These are part of the AXAG specification and MUST be followed for conformance.

### Rule: Required Attributes (Normative)

> Every annotated element **MUST** include `axag-intent`, `axag-entity`, and `axag-action-type`.

```html
<!-- ✅ Conformant: all three required attributes present -->
<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
>Search</button>
```

```html
<!-- ❌ Non-conformant: missing axag-entity and axag-action-type -->
<button axag-intent="product.search">Search</button>
```

### Rule: Risk Level Values (Normative)

> The `axag-risk-level` attribute **MUST** be one of: `none`, `low`, `medium`, `high`, `critical`.

```html
<!-- ✅ Valid risk level -->
<button
  axag-intent="order.cancel"
  axag-entity="order"
  axag-action-type="write"
  axag-risk-level="high"
>Cancel Order</button>
```

```html
<!-- ❌ Invalid risk level value -->
<button
  axag-intent="order.cancel"
  axag-entity="order"
  axag-action-type="write"
  axag-risk-level="dangerous"
>Cancel Order</button>
```

### Rule: Attribute Prefix (Normative)

> All AXAG annotation attributes **MUST** use the `axag-` prefix. This prefix is reserved and **MUST NOT** be used for non-AXAG purposes.

---

## Proposed Implementation Patterns

These patterns are **not part of the formal specification** but represent recommended approaches inferred from the AXAG conceptual model. They are labeled clearly to avoid confusion with normative content.

### Pattern: Async Operation Polling (Proposed)

:::info Proposed Implementation Pattern
This pattern is not part of the normative specification. It represents an inferred best practice.
:::

For async operations, the proposed pattern is to declare the async nature and let the agent framework handle polling:

```html
<button
  axag-intent="report.generate"
  axag-entity="report"
  axag-action-type="read"
  axag-async="true"
  axag-description="Generate analytics report (async, may take 30-60 seconds)"
>Generate Report</button>
```

The corresponding manifest would include:

```json
{
  "intent": "report.generate",
  "entity": "report",
  "async": true,
  "estimated_duration": "30-60s",
  "polling_endpoint": "/api/reports/{job_id}/status"
}
```

**Why this is "proposed":** The specification defines `axag-async` as an optional attribute, but the manifest fields `estimated_duration` and `polling_endpoint` are not part of the normative manifest schema. They are useful extensions that implementations may adopt.

### Pattern: Composite Flow Sequencing (Proposed)

:::info Proposed Implementation Pattern
This pattern shows one approach to declaring multi-step workflows. The specification does not mandate a specific sequencing syntax.
:::

```html
<!-- Step 1 -->
<button
  axag-intent="checkout.validate_cart"
  axag-entity="cart"
  axag-action-type="read"
  axag-postconditions='["cart_valid"]'
  data-axag-flow="checkout"
  data-axag-step="1"
>Validate Cart</button>

<!-- Step 2 -->
<button
  axag-intent="checkout.select_shipping"
  axag-entity="order"
  axag-action-type="write"
  axag-preconditions='["cart_valid"]'
  axag-postconditions='["shipping_selected"]'
  data-axag-flow="checkout"
  data-axag-step="2"
>Select Shipping</button>

<!-- Step 3 -->
<button
  axag-intent="checkout.confirm_payment"
  axag-entity="order"
  axag-action-type="write"
  axag-preconditions='["shipping_selected"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  data-axag-flow="checkout"
  data-axag-step="3"
>Confirm Payment</button>
```

**Why this is "proposed":** The `data-axag-flow` and `data-axag-step` attributes are extensions. The specification does not define flow-level sequencing — it focuses on individual element annotations. Step ordering is inferred through preconditions and postconditions (which ARE normative).

### Pattern: JSON-LD Inline Annotation (Proposed)

:::info Proposed Implementation Pattern
JSON-LD is an alternative annotation format being evaluated for future specification versions.
:::

```html
<script type="application/ld+json">
{
  "@context": "https://axag.org/schema/v1",
  "@type": "AXAGAnnotation",
  "intent": "product.search",
  "entity": "product",
  "actionType": "read",
  "parameters": {
    "required": ["query"],
    "optional": ["category", "price_min", "price_max"]
  },
  "riskLevel": "none",
  "targetSelector": "#search-button"
}
</script>
```

**Why this is "proposed":** The normative annotation format is HTML data attributes (`axag-*`). JSON-LD is being explored as a complementary format for machine-readable page-level declarations.

### Pattern: TypeScript Wrapper Component (Proposed)

:::info Proposed Implementation Pattern
Framework-specific helpers are not part of the specification but are recommended for developer experience.
:::

```typescript

interface AXAGButtonProps extends React.ButtonHTMLAttributes {
  intent: string;
  entity: string;
  actionType: 'read' | 'write' | 'delete' | 'navigate';
  requiredParameters?: string[];
  riskLevel?: 'none' | 'low' | 'medium' | 'high' | 'critical';
  confirmationRequired?: boolean;
  description?: string;
}

  intent, entity, actionType, requiredParameters,
  riskLevel, confirmationRequired, description,
  children, ...rest
}) => (
  <button
    axag-intent={intent}
    axag-entity={entity}
    axag-action-type={actionType}
    axag-required-parameters={requiredParameters ? JSON.stringify(requiredParameters) : undefined}
    axag-risk-level={riskLevel}
    axag-confirmation-required={confirmationRequired?.toString()}
    axag-description={description}
    {...rest}
  >
    {children}
  </button>
);
```

**Why this is "proposed":** The specification is framework-agnostic. React/TypeScript wrappers are implementation helpers, not part of the normative standard.

---

## How to Identify Content Classification

When reading AXAG documentation:

1. **Look for RFC keywords** — `MUST`, `SHOULD`, `MAY` indicate normative content
2. **Check callout boxes** — "Proposed Implementation Pattern" callouts indicate non-normative content
3. **Check page metadata** — Each page declares its classification in the frontmatter or header
4. **Look for the badge** — Normative pages display a classification badge

## Why This Matters

Mixing normative rules with proposed patterns causes:

- **False compliance** — Teams implement proposed patterns thinking they're required
- **Tooling confusion** — Linters enforce proposed patterns as errors
- **Spec drift** — Proposed patterns become de facto standards without review
- **Adoption friction** — Teams unsure what's mandatory vs optional

AXAG maintainers and contributors **MUST** clearly label all content to prevent these issues.

## Next Steps

- [Specification Overview](/docs/specification/overview)
- [Conformance Levels](/docs/specification/conformance-levels)
- [Anti-Patterns](/docs/examples/anti-patterns)

## Frequently Asked Questions

Source: https://axag.org/docs/faq

## General

### What does AXAG stand for?

**Agent Experience Accessibility Guidelines.** AXAG is a semantic annotation standard that makes web UIs machine-readable so AI agents can operate them without scraping.

### How is AXAG different from WCAG?

WCAG makes UIs accessible to *humans* with disabilities. AXAG makes UIs accessible to *AI agents*. WCAG uses ARIA roles and labels; AXAG uses semantic annotations like `axag-intent`, `axag-entity`, and `axag-action-type`. They are complementary — a page can (and should) have both.

### Do I need to change my existing UI framework?

No. AXAG annotations are HTML data attributes that layer on top of any framework — React, Angular, Vue, Svelte, plain HTML. No structural changes needed.

### Is AXAG an official W3C standard?

Not yet. AXAG is a proposed community standard currently at **v1.0.0**. The goal is to evolve it through community adoption and eventually pursue formal standardisation.

---

## Annotations

### What is the minimum viable annotation?

Every annotated element needs at least:
- `axag-intent` — the semantic intent (e.g., `product.search`)
- `axag-entity` — the domain entity (e.g., `product`)
- `axag-action-type` — the operation type (`read`, `write`, or `delete`)

### How do I annotate a multi-step workflow?

Use a separate annotation on each step's submit/action element. Include `axag-preconditions` to encode step ordering (e.g., `"previous step completed"`). See [Multi-Step Workflows](/docs/authoring-guide/annotating-multi-step-workflows).

### Can I annotate dynamically rendered components?

Yes. Annotations are HTML attributes, so they work on dynamically rendered DOM just as well. For React, you can spread AXAG attributes onto elements or wrap them in a reusable component. See [Annotation Reuse](/docs/authoring-guide/annotation-reuse).

### What if an action has no clear entity?

Every action operates on *something*. If it seems entity-less, you may be looking at a composite flow. Break it down. For utility operations (e.g., "export current view"), the entity is the thing being exported (e.g., `report`, `dataset`).

---

## Semantic Manifest

### What is the relationship between annotations and the manifest?

Annotations live *in the HTML*. A semantic manifest is a JSON document *generated from* annotations that describes all available intents, entities, parameters, and constraints for a page or application. Agents consume the manifest, not the raw HTML.

### Where should I host my manifest?

Recommended discovery methods (in priority order):
1. **Well-known URL:** `/.well-known/axag-manifest.json`
2. **HTTP header:** `X-AXAG-Manifest: <url>`
3. **HTML meta tag:** `<meta name="axag-manifest" content="<url>">`

### Can I have multiple manifests?

Yes. Large applications may publish one manifest per section or per page. Agents can discover the relevant manifest through the above discovery mechanisms.

---

## Tool Generation

### How are MCP tools generated from the manifest?

Each intent in the manifest maps to one MCP tool:
- `intent` → tool `name` (dots replaced with underscores)
- `required_parameters`, `optional_parameters` → `input_schema`
- parameter constraints → JSON Schema validations (`enum`, `minimum`, `maximum`, etc.)
- `risk_level`, `confirmation_required` and other safety fields → tool `metadata`

See [Mapping Rules](/docs/tool-generation/mapping-rules).

### Do generated tools handle authentication?

Tools include `axag-required-roles` and `axag-scope` metadata so the MCP runtime can enforce authorization. Actual credential handling is the responsibility of the MCP server and the agent framework.

### Can I customize generated tool names?

The default mapping is `entity_action` (e.g., `product_search`). You can override this in your tool generation pipeline configuration, but the default naming convention is strongly recommended for consistency.

---

## Validation

### What validation tools are available?

- **Static validation:** JSON Schema validation of annotation attributes
- **CI linting:** `npx axag-lint` with rules like `AXAG-LINT-001` (missing intent)
- **Runtime validation:** Parameter validation at agent invocation time

See the [Validation](/docs/validation/static-validation) section.

### How do I add AXAG validation to CI?

Add `npx axag-lint --format=github` to your CI pipeline. It checks all HTML/JSX/TSX files for annotation completeness and schema conformance. See [Add Validation to CI](/docs/tutorials/add-validation-to-ci).

---

## Safety & Risk

### How does risk classification work?

Four levels:
| Level | Meaning | Agent behaviour |
|-------|---------|-----------------|
| `none` | No risk (reads) | Execute freely |
| `low` | Low risk (simple writes) | Execute with logging |
| `medium` | Moderate risk (state changes) | Require confirmation |
| `high` | High risk (payments, deletions) | Require confirmation + review |
| `critical` | Critical (irreversible) | Require multi-party approval |

### What happens if an agent ignores safety metadata?

The safety metadata is advisory. Well-behaved agent frameworks (e.g., MCP-compliant servers) will enforce it. Non-compliant agents may ignore it, which is why AXAG also recommends server-side enforcement of preconditions.

---

## Governance

### Who owns the AXAG standard?

Currently maintained by the community. The governance model follows an open RFC process. See [Ownership Model](/docs/governance/ownership-model).

### How do I propose a change?

1. Open an issue describing the change
2. Create an RFC document following the template
3. Submit a PR and go through the review process

See [Change Review Workflow](/docs/governance/change-review-workflow).

### How is backward compatibility maintained?

AXAG follows semantic versioning. New attributes are additive (non-breaking). Removed or renamed attributes go through a deprecation cycle with at least one minor version of deprecation warnings. See [Backward Compatibility](/docs/governance/backward-compatibility).

---

## Contributing

### How can I contribute?

- Add new use-case domain examples
- Improve documentation
- Write tutorials
- Report issues and propose RFCs
- Build tooling (linters, generators, IDE plugins)

See the [Contributor Guide](/docs/contributors/guide).

### What style conventions should I follow?

See the [Style Guide](/docs/contributors/style-guide) for terminology, formatting, and annotation conventions.


# Contributor Guide

## Contributor Guide

Source: https://axag.org/docs/contributors/guide

Thank you for your interest in contributing to the AXAG Standard! This guide explains how to get involved, the types of contributions we welcome, and the process for submitting changes.

## Ways to Contribute

### 📝 Documentation
- Fix typos, clarify explanations, improve examples
- Add new tutorials or how-to guides
- Translate documentation

### 🗂 Use-Case Domains
- Add annotated examples for new industry verticals
- Expand existing domain examples with additional intents
- See [Adding Use Cases](/docs/contributors/adding-use-cases)

### 🔧 Tooling
- Build linters, validators, or IDE plugins
- Improve the manifest generator pipeline
- Create framework-specific AXAG helper libraries

### 📐 Specification
- Propose new annotation attributes via RFC
- Report ambiguities or inconsistencies
- Suggest improvements to the conformance model

### 🐛 Bug Reports
- Report documentation inaccuracies
- Report schema validation issues
- Report broken examples

---

## Getting Started

### Prerequisites

- Node.js ≥ 18
- npm or pnpm
- Git

### Local Development Setup

```bash
# Clone the repository
git clone https://github.com/me-saurabhkohli/mcp-agentify.git
cd mcp-agentify/axag

# Install dependencies
npm install

# Start the development server
npm start
```

The site will be available at `http://localhost:3000`.

### Project Structure

```
axag/
├── docs/                    # Documentation pages (Markdown/MDX)
│   ├── intro/               # Introduction section
│   ├── getting-started/     # Getting started guides
│   ├── concepts/            # Core concepts
│   ├── specification/       # Formal specification
│   ├── semantic-manifest/   # Manifest documentation
│   ├── tool-generation/     # Tool generation docs
│   ├── authoring-guide/     # Annotation authoring guide
│   ├── use-cases/           # Domain-specific use cases
│   ├── validation/          # Validation documentation
│   ├── governance/          # Governance processes
│   ├── reference/           # Reference materials
│   ├── tutorials/           # Step-by-step tutorials
│   ├── examples/            # Examples and galleries
│   ├── contributors/        # Contributor documentation
│   └── faq.md               # FAQ
├── src/
│   ├── components/          # Custom React components
│   ├── css/                 # Custom styles
│   └── pages/               # Custom pages (homepage)
├── static/                  # Static assets
├── docusaurus.config.ts     # Docusaurus configuration
├── sidebars.ts              # Sidebar navigation
└── package.json             # Dependencies
```

---

## Contribution Workflow

### 1. Find or Create an Issue

- Browse [open issues](https://github.com/me-saurabhkohli/mcp-agentify/issues)
- If your contribution isn't covered by an existing issue, create one first
- Wait for maintainer acknowledgement before starting large changes

### 2. Fork and Branch

```bash
# Fork the repo on GitHub, then:
git checkout -b feature/your-feature-name
```

Branch naming conventions:
- `feature/` — new features or content
- `fix/` — bug fixes or corrections
- `docs/` — documentation-only changes
- `rfc/` — specification proposals

### 3. Make Changes

- Follow the [Style Guide](/docs/contributors/style-guide)
- Add or update tests if applicable
- Ensure all examples validate with `npm run validate`

### 4. Test Locally

```bash
# Build the site
npm run build

# Run validation
npm run validate

# Run linting
npm run lint
```

### 5. Submit a Pull Request

- Write a clear PR description
- Reference the related issue
- Fill out the PR template
- Request review from maintainers

### 6. Review Process

- At least one maintainer review required
- CI checks must pass (build, lint, validate)
- Address review feedback promptly
- See [Review Checklist](/docs/contributors/review-checklist)

---

## Code of Conduct

All contributors are expected to follow our Code of Conduct:

- **Be respectful** — treat everyone with dignity
- **Be constructive** — focus on improving the standard
- **Be inclusive** — welcome diverse perspectives
- **Be patient** — review takes time

---

## Recognition

All contributors are recognised in the project's CONTRIBUTORS file and release notes. Significant contributions are highlighted in the changelog.

## Style Guide

Source: https://axag.org/docs/contributors/style-guide

This guide defines the writing, formatting, and annotation conventions for all AXAG documentation and specification content.

---

## Writing Conventions

### Voice and Tone

- **Active voice** preferred: "The agent reads the manifest" not "The manifest is read by the agent"
- **Second person** for guides and tutorials: "You annotate the button..."
- **Third person** for specification text: "The implementation MUST include..."
- **Present tense** for describing behaviour: "The tool validates parameters"
- Keep sentences **short and clear** — aim for ≤25 words per sentence

### Terminology

Use these terms consistently:

| Preferred Term | Avoid |
|----------------|-------|
| annotation | tag, decorator, markup |
| intent | action name, function name |
| entity | object, resource, model |
| semantic manifest | schema file, config file |
| MCP tool | function, endpoint, API |
| agent | bot, AI, automation |
| risk level | danger level, severity |
| precondition | prerequisite, guard |
| postcondition | result, outcome |
| confirmation | prompt, dialog |
| approval | sign-off, authorisation |

### Normative Language (RFC 2119)

Use these keywords precisely and in **uppercase bold** when stating requirements:

- **MUST** — absolute requirement
- **MUST NOT** — absolute prohibition
- **SHOULD** — recommended but not required
- **SHOULD NOT** — discouraged but not prohibited
- **MAY** — truly optional

Example:
> Every annotated element **MUST** include `axag-intent`, `axag-entity`, and `axag-action-type`.

---

## Formatting Conventions

### Headings

- Use sentence case: "How to annotate a button" not "How To Annotate A Button"
- H1 (`#`) — page title only (one per page, matches frontmatter `title`)
- H2 (`##`) — major sections
- H3 (`###`) — subsections
- Avoid H4+ unless absolutely necessary

### Code Blocks

- Always include the language identifier:
  ````
  ```html
  <button axag-intent="product.search">Search</button>
  ```
  ````
- Use `html` for annotation examples
- Use `json` for manifests and tool schemas
- Use `typescript` or `javascript` for code
- Use `bash` for terminal commands

### Attribute Formatting

- Reference AXAG attributes with backticks and the `axag-` prefix: `axag-intent`
- Reference values with backticks: `"product.search"`, `"read"`, `"high"`
- Use dot notation for intents: `entity.action` (e.g., `product.search`)
- Use snake_case for parameter names: `product_id`, `date_range_start`

### Tables

Use tables for structured comparisons:

```markdown
| Attribute | Type | Required | Description |
|-----------|------|----------|-------------|
| `axag-intent` | string | Yes | Semantic intent identifier |
```

### Admonitions

Use Docusaurus admonitions for callouts:

```markdown
:::tip
Helpful tip here.
:::

:::warning
Important warning here.
:::

:::danger
Critical safety information here.
:::

:::info
Additional context here.
:::

:::note
Side note here.
:::
```

### Lists

- Use bullet lists for unordered items
- Use numbered lists for sequential steps
- Keep list items parallel in structure

---

## Annotation Conventions

### Intent Naming

- Format: `entity.action` in lowercase snake_case
- Entity is singular: `product.search` not `products.search`
- Action is a verb: `search`, `create`, `update`, `delete`, `submit`
- Use domain-specific verbs when clearer: `advance_stage`, `schedule`, `escalate`

### Entity Naming

- Singular lowercase: `product`, `user`, `ticket`
- No prefixes or suffixes: `product` not `ProductEntity` or `tbl_product`
- Match domain language, not database names

### Parameter Naming

- snake_case: `product_id`, `start_date`, `page_size`
- Include the entity prefix for IDs: `product_id` not `id`
- Use `_id` suffix for identifiers: `cart_id`, `user_id`
- Use descriptive names: `date_range_start` not `ds`

### Risk Level Assignment

| Scenario | Risk Level |
|----------|-----------|
| Read-only queries, searches, lists | `none` |
| Creating non-critical records | `low` |
| Updating records, state transitions | `medium` |
| Financial transactions, bulk operations | `high` |
| Permanent deletions, admin operations | `critical` |

---

## Documentation Page Structure

### Specification Pages

1. Title and frontmatter
2. Brief description (1-2 sentences)
3. Schema / attribute table
4. Detailed explanation
5. Examples (annotated HTML + manifest + generated tool)
6. Edge cases / caveats

### Use-Case Pages

1. Title and frontmatter
2. Problem statement
3. Why human-only semantics fail agents
4. AXAG-annotated UI example
5. Resulting semantic manifest excerpt
6. Generated MCP tool
7. Safety and constraints notes

### Tutorial Pages

1. Title and frontmatter
2. What you'll learn
3. Prerequisites
4. Step-by-step instructions (numbered)
5. Verification / testing
6. Next steps

---

## File Naming

- Use kebab-case for file names: `multi-step-workflows.md`
- Use `.md` for pure Markdown
- Use `.mdx` for pages that import React components
- Match the `id` in frontmatter to the filename (without extension)

## Frontmatter Template

```yaml
---
id: page-id
title: Page Title
sidebar_label: Sidebar Label
slug: /section/page-id
---
```

---

## Commit Messages

Follow conventional commits:

```
type(scope): description

docs(use-cases): add travel domain examples
fix(spec): correct risk level table
feat(components): add SchemaFieldTable component
chore(deps): update docusaurus to 3.6.1
```

Types: `docs`, `fix`, `feat`, `chore`, `refactor`, `test`, `ci`

## Adding Use Cases

Source: https://axag.org/docs/contributors/adding-use-cases

This guide explains how to add new domain-specific use cases to the AXAG documentation.

---

## Why Add Use Cases?

Use cases demonstrate AXAG's applicability across industries. Each new domain:
- Validates the standard's expressiveness
- Provides ready-to-use templates for adopters in that industry
- Highlights domain-specific patterns and edge cases

---

## Structure of a Use-Case Page

Every use-case page follows this template:

```markdown
---
id: domain-action
title: "Domain — Action Name"
sidebar_label: Action Name
slug: /use-cases/domain/action-name
---

# Domain — Action Name

## Problem Statement

Describe the user action and its business context. What does the UI look like?
What does the user click, fill in, or interact with?

## Why Human-Only Semantics Fail Agents

Explain why a scraping-based agent would struggle. Mention:
- Ambiguous button labels
- Missing parameter metadata
- Unclear preconditions or risk
- Dynamic rendering challenges

## AXAG-Annotated UI

\`\`\`html
<button
  axag-intent="entity.action"
  axag-entity="entity"
  axag-action-type="write"
  axag-required-parameters='["param1","param2"]'
  ...
>Label</button>
\`\`\`

## Semantic Manifest Excerpt

\`\`\`json
{
  "intent": "entity.action",
  ...
}
\`\`\`

## Generated MCP Tool

\`\`\`json
{
  "name": "entity_action",
  "description": "...",
  "inputSchema": { ... }
}
\`\`\`

## Constraints and Safety

- Risk level and why
- Preconditions and postconditions
- Confirmation/approval requirements
- Side effects

## Why Scraping Fails Here

Specific examples of how a scraping agent would misinterpret
or miss critical metadata for this action.
```

---

## Step-by-Step Process

### 1. Choose a Domain

Check existing domains in `docs/use-cases/`:
- E-Commerce, Marketing, CRM, Travel, Jobs, Analytics, Support, Enterprise

If your domain isn't listed, create a new subdirectory.

### 2. Identify Intents

List the key user actions in the domain. Aim for 2-4 intents per domain:
- At least one **read** operation (search, list, get)
- At least one **write** operation (create, update)
- Optionally a **delete** or **approval** operation

### 3. Create the Directory

```bash
mkdir -p docs/use-cases/your-domain
```

### 4. Write the Pages

Create one `.md` file per intent following the template above.

### 5. Update the Sidebar

Add your domain to `sidebars.ts` under the `use-cases` category:

```typescript
{
  type: 'category',
  label: 'Your Domain',
  items: [
    'use-cases/your-domain/intent-one',
    'use-cases/your-domain/intent-two',
  ],
},
```

### 6. Update the Overview

Add your domain to `docs/use-cases/overview.md`:
- Add a row to the domain comparison table
- Add a brief description

### 7. Validate

```bash
npm run build
npm run validate
```

---

## Naming Conventions

| Element | Convention | Example |
|---------|-----------|---------|
| Directory | kebab-case | `your-domain/` |
| File | kebab-case | `action-name.md` |
| Intent | entity.action | `invoice.create` |
| Entity | singular lowercase | `invoice` |
| Page ID | `domain-action` | `finance-invoice-create` |

---

## Quality Checklist

Before submitting:

- [ ] Page follows the standard template structure
- [ ] All six sections present (problem, why agents fail, annotation, manifest, tool, safety)
- [ ] Annotations include all required attributes (`axag-intent`, `axag-entity`, `axag-action-type`)
- [ ] Risk level is appropriate for the action
- [ ] Preconditions and postconditions are realistic
- [ ] Manifest excerpt is valid JSON
- [ ] Generated tool example is valid JSON
- [ ] Page builds without errors
- [ ] Sidebar entry added
- [ ] Overview page updated

---

## Example PR

Here's what a good use-case contribution PR looks like:

```
feat(use-cases): add finance domain with invoice and payment intents

- Add docs/use-cases/finance/invoice-creation.md
- Add docs/use-cases/finance/payment-processing.md
- Update sidebars.ts with finance category
- Update use-cases/overview.md with finance domain
- All examples validate against AXAG schema

Closes #42
```

## Review Checklist

Source: https://axag.org/docs/contributors/review-checklist

Use this checklist when reviewing pull requests to the AXAG documentation.

---

## General

- [ ] PR description clearly explains the change
- [ ] Related issue is linked
- [ ] Branch is up-to-date with `main`
- [ ] CI checks pass (build, lint, validate)

## Content Quality

- [ ] Content is technically accurate
- [ ] Writing follows the [Style Guide](/docs/contributors/style-guide)
- [ ] Normative language (MUST, SHOULD, MAY) used correctly per RFC 2119
- [ ] No spelling or grammar errors
- [ ] No broken links
- [ ] Appropriate use of admonitions (tip, warning, danger, info, note)

## Annotation Examples

- [ ] All examples include required attributes (`axag-intent`, `axag-entity`, `axag-action-type`)
- [ ] Intent names follow `entity.action` convention
- [ ] Parameter names use snake_case
- [ ] Risk levels are appropriate for the action type
- [ ] Constraints use valid JSON Schema patterns
- [ ] Preconditions and postconditions are realistic
- [ ] Side effects are documented where applicable
- [ ] `axag-idempotent` is set correctly

## JSON Examples

- [ ] All JSON is valid (parseable)
- [ ] Manifest excerpts match the annotation they describe
- [ ] Generated tool examples match the manifest they derive from
- [ ] `inputSchema` uses correct JSON Schema types
- [ ] Required fields in schema match `axag-required-parameters`

## Page Structure

- [ ] Frontmatter includes `id`, `title`, `sidebar_label`, `slug`
- [ ] `id` matches filename (without extension)
- [ ] Page follows the appropriate template (spec, use-case, tutorial, etc.)
- [ ] All expected sections are present
- [ ] Heading hierarchy is correct (H1 → H2 → H3, no skipping)

## Navigation

- [ ] Sidebar entry added in `sidebars.ts`
- [ ] Slug is correct and follows conventions
- [ ] Cross-references link to the right pages
- [ ] No orphaned pages (every page reachable from sidebar)

## MDX Components

- [ ] Component imports are correct (if `.mdx` file)
- [ ] Components render correctly in dev server
- [ ] No missing required props
- [ ] Component usage follows established patterns

## Use-Case Specific

- [ ] Problem statement is clear and domain-specific
- [ ] "Why agents fail" section explains scraping limitations
- [ ] Annotated UI example is realistic
- [ ] Manifest excerpt matches the annotation
- [ ] Generated MCP tool matches the manifest
- [ ] Safety section covers risk, preconditions, postconditions, side effects

## Specification Changes

- [ ] RFC document provided for new attributes or changes
- [ ] Backward compatibility impact assessed
- [ ] Schema reference updated
- [ ] Glossary updated if new terms introduced
- [ ] Version policy followed

---

## Review Decision Guide

| Situation | Action |
|-----------|--------|
| Minor typo or formatting fix | Approve with suggestion |
| Content is correct but could be clearer | Request changes (non-blocking) |
| Missing required sections | Request changes (blocking) |
| Invalid JSON or annotation examples | Request changes (blocking) |
| New attribute without RFC | Request changes (blocking) |
| Breaking change without deprecation plan | Request changes (blocking) |


# Other pages

## ADR 001: Docusaurus as Documentation Platform

Source: https://axag.org/docs/adr/001-docusaurus

## Status

**Accepted** — 2024-01

## Context

The AXAG standard requires a documentation platform that supports:

1. **Versioned documentation** — the spec evolves across versions
2. **MDX support** — interactive components embedded in documentation
3. **Sidebar navigation** — deep information architecture (16+ categories)
4. **Code syntax highlighting** — HTML, JSON, TypeScript, YAML examples
5. **Diagram support** — architecture and flow diagrams
6. **Search** — full-text search across all documentation
7. **SEO** — discoverability for standard adoption
8. **Static site generation** — fast, deployable to any CDN
9. **Developer familiarity** — React/TypeScript ecosystem

## Decision

We will use **Docusaurus 3.x** as the documentation platform.

## Rationale

### Evaluated Options

| Criterion | Docusaurus | VitePress | MkDocs | GitBook |
|-----------|-----------|-----------|--------|---------|
| Versioned docs | ✅ Built-in | ❌ Manual | ⚠️ Plugin | ✅ Built-in |
| MDX / React components | ✅ Native | ❌ Vue only | ❌ No | ❌ Limited |
| Sidebar depth | ✅ Unlimited | ✅ Good | ✅ Good | ⚠️ Limited |
| Mermaid diagrams | ✅ Plugin | ✅ Plugin | ✅ Plugin | ✅ Built-in |
| Static site | ✅ Yes | ✅ Yes | ✅ Yes | ❌ Hosted |
| TypeScript | ✅ Native | ✅ Native | ❌ Python | ❌ N/A |
| Community | ✅ Large | ✅ Growing | ✅ Large | ⚠️ Proprietary |

### Why Docusaurus

- **Versioned docs** out of the box — critical for a specification that evolves
- **MDX support** — enables interactive components like `SchemaFieldTable`, `NormativeCallout`, `BeforeAfter` directly in documentation
- **React ecosystem** — team familiarity, rich component library
- **Proven at scale** — used by React, Jest, Babel, many other open source projects
- **Plugin architecture** — Mermaid, search, analytics all available

### Trade-offs

- Heavier than VitePress for simple sites (acceptable for our complexity)
- React-specific (acceptable given team skills)
- Build times increase with page count (mitigated by incremental builds)

## Consequences

- All documentation written in Markdown/MDX
- Custom interactive components built with React/TypeScript
- Deployable to GitHub Pages, Vercel, Netlify, or any static host
- Contributors need basic React knowledge for MDX components
- Configuration in `docusaurus.config.ts` and `sidebars.ts`