Skip to main content

Tutorial: Generate a Semantic Manifest

This tutorial walks through generating an AXAG Semantic Manifest from annotated HTML/JSX source files.

Prerequisites​

Step 1: Install the CLI​

Install AXAG CLI
npm install -D @axag/cli

Step 2: Scan Source Files​

Scan & generate manifest
npx axag scan --input src/ --output axag-manifest.json

The scanner:

  1. Finds all files with axag-* attributes (.html, .jsx, .tsx, .vue, .svelte)
  2. Extracts annotation data from each element
  3. Groups actions by entity
  4. Outputs a structured Semantic Manifest

Step 3: Review the Generated Manifest​

axag-manifest.json
{
  "version": "0.1.0-draft",
  "metadata": {
    "generator": "@axag/cli@0.1.0",
    "generated_at": "2024-01-15T10:30:00Z",
    "source_files": ["src/SearchPage.tsx", "src/CartPage.tsx", "src/AdminPage.tsx"]
  },
  "entities": [
    {
      "name": "product",
      "actions": [
        {
          "intent": "product.search",
          "operation_id": "product_search",
          "action_type": "read",
          "description": "Search the product catalog",
          "parameters": {
            "query": { "type": "string", "required": true }
          },
          "risk_level": "none",
          "idempotent": true
        }
      ]
    }
  ]
}

Step 4: Validate the Manifest​

Validate manifest
npx axag validate-manifest axag-manifest.json

Expected output:

Validation output
✓ Manifest schema is valid
✓ All intents follow naming convention
✓ All required fields present
✓ 12 actions across 4 entities

Step 5: Serve the Manifest​

Make the manifest discoverable by agents:

Option A: Well-Known URL​

Well-known endpoint
https://yoursite.com/.well-known/axag-manifest.json

Option B: HTTP Header​

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

Option C: HTML Meta Tag​

HTML meta tag
<meta name="axag-manifest" content="/.well-known/axag-manifest.json">

Step 6: Automate in CI​

.github/workflows/axag.yml
# .github/workflows/axag.yml
- name: Generate manifest
  run: npx axag scan --input src/ --output axag-manifest.json

- name: Validate manifest
  run: npx axag validate-manifest axag-manifest.json

- name: Deploy manifest
  run: cp axag-manifest.json public/.well-known/axag-manifest.json

Next Steps​