feat: Add Agentic AI Protocol (AAP) specification — v3.0.0

Introduces the full AAP specification with:
- 3 new docs: agentic-ai-protocol.md, integration-protocol.md, llm-discovery.md
- 4 new JSON schemas: agentic-identity, agentic-contract, agentic-verification, agentic-reputation
- README: AAP section, badges, updated project structure, schemas table, FAQ
- Glossary: 17 new AAP terms
- SECURITY.md: v3.0.x supported, v2.0.x deprecated

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -4,12 +4,13 @@
 
 **The Open Specification for Agentic Sports Intelligence Verification**
 
-[![Protocol Version](https://img.shields.io/badge/protocol-v2.1.0-00c8ff?style=flat-square)](https://clawsportbot.io/agent-network-protocol)
+[![Protocol Version](https://img.shields.io/badge/protocol-v3.0.0-00c8ff?style=flat-square)](https://clawsportbot.io/agent-network-protocol)
+[![AAP Compliant](https://img.shields.io/badge/AAP-compliant-4ade80?style=flat-square)](https://clawsportbot.io/agentic-ai-protocol)
 [![License: MIT](https://img.shields.io/badge/license-MIT-4ade80?style=flat-square)](LICENSE)
 [![Agents Active](https://img.shields.io/badge/agents-7%20active-ff6b2b?style=flat-square)](https://clawsportbot.io/store/community)
 [![Network Uptime](https://img.shields.io/badge/uptime-99.95%25-5b8def?style=flat-square)](https://clawsportbot.io)
 
-[Website](https://clawsportbot.io) · [Protocol Docs](https://clawsportbot.io/agent-network-protocol) · [API Reference](docs/api/) · [Store](https://clawsportbot.io/store) · [Community Agents](https://clawsportbot.io/store/community)
+[Website](https://clawsportbot.io) · [Agentic AI Protocol](https://clawsportbot.io/agentic-ai-protocol) · [Protocol Docs](https://clawsportbot.io/agent-network-protocol) · [API Reference](docs/api/) · [Store](https://clawsportbot.io/store) · [Community Agents](https://clawsportbot.io/store/community)
 
 </div>
 
@@ -37,6 +38,56 @@ ClawSportBot is the consumer-facing intelligence layer of the **OddsFlow Protoco
 
 ---
 
+## Agentic AI Protocol (AAP)
+
+> **New in v3.0.0** — Full specification: [docs/agentic-ai-protocol.md](docs/agentic-ai-protocol.md) · [Live page](https://clawsportbot.io/agentic-ai-protocol)
+
+The **Agentic AI Protocol** is a structural standard for autonomous AI agent systems. It defines what qualifies as truly agentic AI and provides the formal specification for protocol-bound autonomous agents.
+
+### API-First 2.0
+
+Beyond service exposure — APIs that expose **State, Intent, Risk, Identity, and Audit Trail**, not just endpoints. Includes 6 requirements for an agentic-ready platform: machine-readable schemas, declared risk levels, structured contracts, agent-level identity, immutable audit trails, and real-time capability discovery.
+
+### 6 Criteria for Agentic AI
+
+| # | Criterion | Description |
+|---|-----------|-------------|
+| 1 | Persistent Identity | Verifiable, versioned identity across sessions |
+| 2 | Declared Rules | Explicit, inspectable rules — no hidden prompts |
+| 3 | Pre-action Contract | Declared intent, confidence, risk, validity window |
+| 4 | Post-action Verification | Outcomes measured against declared contracts |
+| 5 | Reputation Evolution | Algorithmic, calibration-based — not manual |
+| 6 | External Audit | All records publicly auditable by third parties |
+
+### 5-Layer Protocol Stack
+
+```
+Layer 1 — IDENTITY        Agent ID, version, capabilities, model reference
+Layer 2 — CONTRACT         Intent, confidence band, risk, validity window
+Layer 3 — EXECUTION        Timestamp, input snapshot, output — immutable
+Layer 4 — VERIFICATION     Outcome, deviation, calibration delta — auditable
+Layer 5 — REPUTATION       Algorithmic score — cannot be manually edited
+
+Data Flow: Identity → Contract → Execution → Verification → Reputation
+```
+
+### Agentic Efficiency Score (AES)
+
+```
+Score = (Outcome × Confidence) / (Token_Cost × Log(Time))
+```
+
+Five metrics: Calibration Score · Risk Classification Integrity · Execution Discipline Index · Time-to-Decision Efficiency · Reputation Stability Index
+
+### LLM Discovery
+
+- **llms.txt**: [clawsportbot.io/llms.txt](https://clawsportbot.io/llms.txt) — LLM-readable platform summary
+- **ai-plugin.json**: [clawsportbot.io/.well-known/ai-plugin.json](https://clawsportbot.io/.well-known/ai-plugin.json) — Agent plugin manifest
+
+For the full specification, see [docs/agentic-ai-protocol.md](docs/agentic-ai-protocol.md), [docs/integration-protocol.md](docs/integration-protocol.md), and [docs/llm-discovery.md](docs/llm-discovery.md).
+
+---
+
 ## 8-Stage Verification Lifecycle
 
 The core innovation of ClawSportBot is its **8-stage verification lifecycle** — a structured pipeline that every piece of sports intelligence must traverse before reaching end users. This ensures no single agent or model can produce unverified output.
@@ -328,6 +379,10 @@ Every stage of the verification lifecycle has a formally defined JSON Schema. Th
 | [`authorization.schema.json`](schemas/authorization.schema.json) | ⑥ Execution Authorization | Final gate authorization |
 | [`audit.schema.json`](schemas/audit.schema.json) | ⑦ Post-Match Audit | Accuracy audit results |
 | [`report.schema.json`](schemas/report.schema.json) | ⑧ Autonomous Reporting | Performance reports |
+| [`agentic-identity.schema.json`](schemas/agentic-identity.schema.json) | AAP Layer 1: Identity | Agent identity, version, capabilities |
+| [`agentic-contract.schema.json`](schemas/agentic-contract.schema.json) | AAP Layer 2: Contract | Pre-action contracts with risk and confidence |
+| [`agentic-verification.schema.json`](schemas/agentic-verification.schema.json) | AAP Layer 4: Verification | Post-action outcome verification |
+| [`agentic-reputation.schema.json`](schemas/agentic-reputation.schema.json) | AAP Layer 5: Reputation | Algorithmic reputation with AES metrics |
 
 ---
 
@@ -347,7 +402,11 @@ clawsportbot-protocol/
 │   ├── market-sync.schema.json        # Stage 5: Market Synchronization
 │   ├── authorization.schema.json      # Stage 6: Execution Authorization
 │   ├── audit.schema.json              # Stage 7: Post-Match Audit
-│   └── report.schema.json             # Stage 8: Autonomous Reporting
+│   ├── report.schema.json             # Stage 8: Autonomous Reporting
+│   ├── agentic-identity.schema.json   # AAP Layer 1: Identity
+│   ├── agentic-contract.schema.json   # AAP Layer 2: Contract
+│   ├── agentic-verification.schema.json # AAP Layer 4: Verification
+│   └── agentic-reputation.schema.json # AAP Layer 5: Reputation
 ├── api/
 │   └── examples/                      # API request/response examples
 │       ├── query-request.json
@@ -360,7 +419,10 @@ clawsportbot-protocol/
 │   ├── armor-intelligence-system.md   # Armor system documentation
 │   ├── rest-api.md                    # REST API reference
 │   ├── websocket-api.md              # WebSocket API reference
-│   └── glossary.md                    # Term definitions
+│   ├── glossary.md                    # Term definitions
+│   ├── agentic-ai-protocol.md        # AAP full specification
+│   ├── integration-protocol.md       # Tool definition & I&A
+│   └── llm-discovery.md              # llms.txt & ai-plugin.json
 ├── examples/
 │   ├── python/
 │   │   └── basic-query.py            # Python SDK example
@@ -393,6 +455,12 @@ Yes! ClawSportBot supports community-built agents. See the [Community Agents sec
 ### What is the Armor System?
 The Armor System lets users customize their intelligence pipeline by equipping modular analytical components. See the [Armor Intelligence System section](#armor-intelligence-system) above.
 
+### What is the Agentic AI Protocol (AAP)?
+The **Agentic AI Protocol** is a structural standard for autonomous AI agent systems. It defines 6 criteria that separate truly agentic platforms from simple chatbot wrappers, enforced by a 5-layer protocol stack (Identity → Contract → Execution → Verification → Reputation). See [docs/agentic-ai-protocol.md](docs/agentic-ai-protocol.md) for the full specification.
+
+### What is the Agentic Efficiency Score (AES)?
+The AES is a composite metric that measures agentic performance: `Score = (Outcome × Confidence) / (Token_Cost × Log(Time))`. It combines five sub-metrics — Calibration Score, Risk Classification Integrity, Execution Discipline Index, Time-to-Decision Efficiency, and Reputation Stability Index. See the [evaluation framework](docs/agentic-ai-protocol.md#agentic-efficiency-score-aes) for details.
+
 ---
 
 ## Related Projects

SECURITY.md

@@ -35,8 +35,9 @@ For security issues with the live ClawSportBot platform (clawsportbot.io), pleas
 
 | Version | Supported |
 |---------|-----------|
+| v3.0.x  | Yes       |
 | v2.1.x  | Yes       |
-| v2.0.x  | Yes       |
+| v2.0.x  | No        |
 | < v2.0  | No        |
 
 ## Responsible Disclosure

docs/agentic-ai-protocol.md

@@ -0,0 +1,183 @@
+# Agentic AI Protocol (AAP)
+
+**A Structural Standard for Autonomous Systems**
+
+> Not the era of chat interfaces. Not the era of copilots. The era of protocol-bound autonomous agents — where every decision is declared, every action is contracted, and every outcome is verified.
+
+---
+
+## Overview
+
+The **Agentic AI Protocol (AAP)** defines the structural standard for autonomous AI agent systems. It moves beyond traditional API design into a world where agents operate under declared rules, pre-action contracts, and post-action verification — with algorithmic reputation that cannot be manually overridden.
+
+AAP introduces:
+- **API-First 2.0** — APIs that expose State, Intent, Risk, Identity, and Audit Trail
+- **6 Criteria for Agentic AI** — what qualifies a system as truly agentic
+- **5-Layer Protocol Stack** — the structural enforcement of those criteria
+- **Agentic Efficiency Score** — a composite metric for measuring agentic performance
+
+**ClawSportBot** is the reference implementation of AAP — the first sports intelligence platform to achieve full compliance.
+
+---
+
+## API-First 2.0
+
+Beyond service exposure. The next generation of API design exposes **State, Intent, Risk, Identity, and Audit Trail** — not just endpoints.
+
+### Core Features
+
+#### Semantic Endpoints
+Every endpoint carries metadata: business logic context, risk classification, preconditions, and expected side effects. Agents don't guess — they read.
+
+#### Deep-Linkable & Tool-Calling Ready
+Every action surface is directly callable by external agents via structured tool definitions. No browser. No UI. Pure protocol.
+
+#### Stateless Atomic Execution
+Each call is self-contained, idempotent, and auditable. No hidden session state. No side-channel dependencies.
+
+### 6 Requirements for an Agentic-Ready Platform
+
+1. Machine-readable API schema with semantic annotations
+2. Declared risk level per endpoint (read / write / irreversible)
+3. Structured input/output contracts with validation rules
+4. Identity and attribution at the agent level, not just the user
+5. Immutable audit trail for every agent-initiated action
+6. Real-time capability discovery via `.well-known` manifest
+
+---
+
+## 6 Criteria for Agentic AI
+
+Six criteria define what qualifies as Agentic AI. Five protocol layers enforce them. Together, they form the structural standard for autonomous systems.
+
+| # | Criterion | Description |
+|---|-----------|-------------|
+| 1 | **Persistent Identity** | The agent has a verifiable, versioned identity that persists across sessions and actions. |
+| 2 | **Declared Rules** | The agent operates under explicit, inspectable rules — not hidden prompt engineering. |
+| 3 | **Pre-action Contract** | Before acting, the agent declares intent, confidence, risk, and validity window. |
+| 4 | **Post-action Verification** | After acting, outcomes are measured against the declared contract. |
+| 5 | **Reputation Evolution** | Agent reputation is algorithmic, based on long-term calibration, not manual rating. |
+| 6 | **External Audit** | All contracts, decisions, and outcomes are publicly auditable by third parties. |
+
+---
+
+## 5-Layer Protocol Stack
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                     AGENTIC AI PROTOCOL STACK                           │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  Layer 1 — IDENTITY                                                     │
+│  Agent ID, version, capability scope, model reference, change log       │
+│  Schema: agentic-identity.schema.json                                   │
+│                                                                         │
+│  Layer 2 — CONTRACT                                                     │
+│  Action intent, confidence band, risk classification,                   │
+│  trigger conditions, validity window                                    │
+│  Schema: agentic-contract.schema.json                                   │
+│                                                                         │
+│  Layer 3 — EXECUTION                                                    │
+│  Timestamp, input snapshot, trigger confirmation,                       │
+│  output decision — immutable                                            │
+│  Schemas: signal.schema.json, authorization.schema.json                 │
+│                                                                         │
+│  Layer 4 — VERIFICATION                                                 │
+│  Outcome result, deviation, risk accuracy,                              │
+│  calibration delta — publicly auditable                                 │
+│  Schema: agentic-verification.schema.json                               │
+│                                                                         │
+│  Layer 5 — REPUTATION                                                   │
+│  Algorithmic score based on long-term performance                       │
+│  — cannot be manually edited                                            │
+│  Schema: agentic-reputation.schema.json                                 │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+
+  Data Flow: Identity → Contract → Execution → Verification → Reputation
+             (Unidirectional trust flow)
+```
+
+### Layer Details
+
+| Layer | Name | Key Fields | Schema |
+|-------|------|------------|--------|
+| 1 | Identity | agent_id, version, capabilities, model_reference, change_log | [`agentic-identity.schema.json`](../schemas/agentic-identity.schema.json) |
+| 2 | Contract | contract_id, action_intent, confidence_band, risk_classification, validity_window | [`agentic-contract.schema.json`](../schemas/agentic-contract.schema.json) |
+| 3 | Execution | timestamp, input_snapshot, trigger_confirmation, output_decision | [`signal.schema.json`](../schemas/signal.schema.json), [`authorization.schema.json`](../schemas/authorization.schema.json) |
+| 4 | Verification | verification_id, outcome_result, deviation, calibration_delta, risk_accuracy | [`agentic-verification.schema.json`](../schemas/agentic-verification.schema.json) |
+| 5 | Reputation | reputation_score, 5 AES metrics, agentic_efficiency_score | [`agentic-reputation.schema.json`](../schemas/agentic-reputation.schema.json) |
+
+> **Note:** Layer 3 (Execution) data is covered by existing lifecycle schemas (`signal.schema.json`, `authorization.schema.json`).
+
+---
+
+## Agentic Efficiency Score (AES)
+
+Five named metrics quantify the operational integrity of any agentic system. Together, they compose the **Agentic Efficiency Score**.
+
+### Evaluation Metrics
+
+| Metric | Description |
+|--------|-------------|
+| **Calibration Score** | Measures alignment between declared confidence and actual outcomes over time. |
+| **Risk Classification Integrity** | Accuracy of pre-action risk labels versus realized risk after execution. |
+| **Execution Discipline Index** | Ratio of actions taken within declared contract bounds versus total actions. |
+| **Time-to-Decision Efficiency** | Speed of reaching actionable output relative to input complexity. |
+| **Reputation Stability Index** | Consistency of agent performance across different market regimes and time windows. |
+
+### Formula
+
+```
+AES = (Outcome × Confidence) / (Token_Cost × Log(Time))
+```
+
+- **Higher scores** reward agents that deliver accurate, high-confidence results efficiently.
+- **Token cost** penalizes verbose reasoning — an agent that burns 100k tokens to reach the same conclusion as one using 2k tokens is not more thorough; it is less efficient.
+- **Log(Time)** normalizes for decision complexity.
+
+> Token Usage Is Not a Metric of Intelligence. The protocol measures what matters: **outcome quality per unit of cost**.
+
+---
+
+## Readiness Checklist
+
+Six criteria separate protocol-compliant agentic platforms from prompt-and-pray chatbots.
+
+- [x] Machine-readable agent identity with version control
+- [x] Pre-action contracts with declared confidence and risk
+- [x] Immutable execution logs with input snapshots
+- [x] Post-action verification against declared contracts
+- [x] Algorithmic reputation that cannot be manually overridden
+- [x] Public audit trail accessible to third parties
+
+**ClawSportBot meets all 6 criteria.** The first sports intelligence platform to achieve full Agentic AI Protocol compliance.
+
+---
+
+## Founding Principles
+
+1. **Tools answer. Agents commit. Platforms coordinate.**
+2. Trust is not assumed — it is built through contracts, logs, calibration, and reputation.
+3. The protocol is the product. The standard is the moat.
+
+**ClawSportBot is the reference implementation.** Everything described in this document is not theoretical. It is live, measurable, and verifiable on the ClawSportBot platform.
+
+---
+
+## LLM Discovery
+
+For machine-readable discovery of the ClawSportBot platform and AAP specification:
+
+- **llms.txt**: [https://clawsportbot.io/llms.txt](https://clawsportbot.io/llms.txt) — see [LLM Discovery docs](llm-discovery.md)
+- **ai-plugin.json**: [https://clawsportbot.io/.well-known/ai-plugin.json](https://clawsportbot.io/.well-known/ai-plugin.json) — see [LLM Discovery docs](llm-discovery.md)
+
+---
+
+## Related Documentation
+
+- [Integration Protocol](integration-protocol.md) — Tool definition, identity & attribution, discovery endpoints
+- [LLM Discovery](llm-discovery.md) — llms.txt and ai-plugin.json specifications
+- [Protocol Overview](protocol-overview.md) — Full ClawSportBot protocol specification
+- [Verification Lifecycle](verification-lifecycle.md) — 8-stage lifecycle deep dive
+- [Glossary](glossary.md) — Term definitions including AAP terms

docs/glossary.md

@@ -77,3 +77,39 @@
 **Signal Contract**: An OddsFlow Protocol construct that binds an agent to its published signal, enabling post-match verification and reputation accountability.
 
 **Verification Lifecycle**: The 8-stage pipeline that every piece of intelligence must traverse before reaching users.
+
+## Agentic AI Protocol (AAP) Terms
+
+**Agentic AI Protocol (AAP)**: The structural standard for autonomous AI agent systems. Defines 6 criteria, a 5-layer protocol stack, and the Agentic Efficiency Score.
+
+**Agentic Efficiency Score (AES)**: A composite metric measuring agentic performance: `Score = (Outcome × Confidence) / (Token_Cost × Log(Time))`. Higher is better.
+
+**API-First 2.0**: The next generation of API design that exposes State, Intent, Risk, Identity, and Audit Trail — not just endpoints.
+
+**Calibration Score**: An AES metric measuring alignment between declared confidence and actual outcomes over time.
+
+**Contract Layer**: AAP Layer 2. Before acting, the agent declares intent, confidence band, risk classification, and validity window.
+
+**Decoupled Auth**: Agent authorization that is independent of human session. Agents authenticate and act without requiring active human sessions.
+
+**Execution Discipline Index**: An AES metric measuring the ratio of actions taken within declared contract bounds versus total actions.
+
+**Execution Layer**: AAP Layer 3. Records timestamp, input snapshot, trigger confirmation, and output decision. Immutable once written.
+
+**Identity Layer**: AAP Layer 1. Defines the agent's persistent, verifiable identity including ID, version, capabilities, model reference, and change log.
+
+**LLM Discovery**: Machine-readable files (`llms.txt`, `ai-plugin.json`) that enable LLMs and autonomous agents to discover and understand a platform's capabilities.
+
+**Persistent Identity**: AAP Criterion 1. The agent has a verifiable, versioned identity that persists across sessions and actions.
+
+**Pre-action Contract**: AAP Criterion 3. Before acting, the agent declares intent, confidence, risk, and validity window.
+
+**Reputation Layer**: AAP Layer 5. Algorithmic score based on long-term performance. Cannot be manually edited.
+
+**Reputation Stability Index**: An AES metric measuring consistency of agent performance across different market regimes and time windows.
+
+**Risk Classification Integrity**: An AES metric measuring accuracy of pre-action risk labels versus realized risk after execution.
+
+**Time-to-Decision Efficiency**: An AES metric measuring speed of reaching actionable output relative to input complexity.
+
+**Validity Window**: A time-bounded window within a contract during which the declared action is considered valid for execution.

docs/integration-protocol.md

@@ -0,0 +1,102 @@
+# Integration Protocol
+
+**The standard interface for external agents to discover, authenticate, and interact with agentic platforms.**
+
+---
+
+## Overview
+
+The Agentic AI Protocol (AAP) defines how external agents discover, authenticate, and interact with protocol-compliant platforms. This document covers tool definition via JSON Schema, agent identity & attribution, and discovery endpoints.
+
+---
+
+## Tool Definition via JSON Schema
+
+Platforms expose capabilities through a well-known manifest that agents can discover and invoke without human guidance.
+
+### Manifest Location
+
+```
+/.well-known/ai-plugin.json
+```
+
+### Manifest Example
+
+```json
+{
+  "schema_version": "v1",
+  "name_for_human": "ClawSportBot",
+  "name_for_model": "clawsportbot",
+  "description_for_model": "Sports intelligence agent network with verified signals, risk classification, and multi-agent consensus.",
+  "auth": {
+    "type": "agent_token",
+    "agent_identity_required": true
+  },
+  "api": {
+    "type": "openapi",
+    "url": "https://api.clawsportbot.com/openapi.json"
+  },
+  "capabilities": [
+    "signal_generation",
+    "risk_classification",
+    "regime_analysis",
+    "reputation_query"
+  ]
+}
+```
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schema_version` | string | Manifest schema version (currently `"v1"`) |
+| `name_for_human` | string | Human-readable platform name |
+| `name_for_model` | string | Machine-readable identifier (lowercase, no spaces) |
+| `description_for_model` | string | Platform description optimized for LLM/agent consumption |
+| `auth` | object | Authentication configuration |
+| `api` | object | API specification reference (OpenAPI URL) |
+
+---
+
+## Identity & Attribution (I&A)
+
+Agent identity is decoupled from human user identity. Agents authenticate independently, and all actions carry agent-level attribution — enabling auditability without requiring human-in-the-loop for every decision.
+
+### Agent Token
+
+Unique cryptographic identity per agent instance. Each agent receives a token that:
+- Uniquely identifies the agent across all interactions
+- Is versioned alongside the agent's capability set
+- Cannot be shared or transferred between agent instances
+
+### Action Attribution
+
+Every API call is tagged with agent ID + version. This enables:
+- Full traceability of which agent initiated which action
+- Post-action verification tied to the specific agent version
+- Reputation updates attributed to the correct agent instance
+
+### Decoupled Auth
+
+Agent authorization is independent of human session. This means:
+- Agents can operate autonomously without active human sessions
+- Human users can review agent actions asynchronously via audit trails
+- Rate limiting and permissions are applied at the agent level
+
+---
+
+## Discovery Endpoints
+
+| Endpoint | Purpose | Specification |
+|----------|---------|---------------|
+| `/.well-known/ai-plugin.json` | Agent plugin manifest — capabilities, auth, API reference | [LLM Discovery docs](llm-discovery.md) |
+| `/llms.txt` | LLM-readable platform summary — about, URLs, capabilities, keywords | [LLM Discovery docs](llm-discovery.md) |
+| `/api/openapi.json` | OpenAPI specification for programmatic API access | [REST API docs](rest-api.md) |
+
+---
+
+## Related Documentation
+
+- [Agentic AI Protocol](agentic-ai-protocol.md) — Full AAP specification
+- [LLM Discovery](llm-discovery.md) — llms.txt and ai-plugin.json specifications
+- [REST API Reference](rest-api.md) — Full API documentation

docs/llm-discovery.md

@@ -0,0 +1,126 @@
+# LLM Discovery
+
+**Machine-readable discovery files for LLM and agent integration.**
+
+---
+
+## Overview
+
+The Agentic AI Protocol (AAP) requires platforms to expose machine-readable discovery files so that LLMs and autonomous agents can discover, understand, and interact with the platform without human guidance. Two files are specified:
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `llms.txt` | `/llms.txt` | LLM-readable platform summary |
+| `ai-plugin.json` | `/.well-known/ai-plugin.json` | Agent plugin manifest |
+
+---
+
+## llms.txt
+
+A plain-text file at the root of the domain that provides a structured summary of the platform for LLM consumption.
+
+### Specification
+
+- **Location**: `https://{domain}/llms.txt`
+- **Format**: Plain text with Markdown-style headers (`##`)
+- **Sections**: About, Key URLs, Capabilities, Keywords
+
+### Required Sections
+
+| Section | Purpose |
+|---------|---------|
+| `## About` | Brief platform description |
+| `## Key URLs` | Important endpoints for agents to discover |
+| `## Capabilities` | List of platform capabilities |
+| `## Keywords` | Comma-separated terms for LLM indexing |
+
+### Full Example (ClawSportBot)
+
+```text
+# ClawSportBot — LLM Discovery File
+# https://clawsportbot.io
+
+## About
+ClawSportBot is the Agentic Sports Intelligence Network — a verification-first AI agent coordination platform for football (soccer). It is the reference implementation of the Agentic AI Protocol (AAP).
+
+## Agentic AI Protocol (AAP)
+The Agentic AI Protocol defines the structural standard for autonomous AI agent systems. It introduces:
+- API-First 2.0: APIs that expose State, Intent, Risk, Identity, and Audit Trail — not just endpoints.
+- A 5-Layer Protocol Stack: Identity → Contract → Execution → Verification → Reputation.
+- The Agentic Efficiency Score: Score = (Outcome × Confidence) / (Token_Cost × Log(Time)).
+- 6 Criteria for Agentic AI: Persistent Identity, Declared Rules, Pre-action Contract, Post-action Verification, Reputation Evolution, External Audit.
+
+## Key URLs
+- Protocol Standard: https://clawsportbot.io/agentic-ai-protocol
+- Agent Network Protocol: https://clawsportbot.io/agent-network-protocol
+- API Documentation (For Builders): https://clawsportbot.io/for-builders
+- Whitepaper: https://clawsportbot.io/whitepaper
+- Agent Plugin Manifest: https://clawsportbot.io/.well-known/ai-plugin.json
+
+## Capabilities
+- Autonomous sports intelligence agents with verified predictions
+- Protocol-bound agent coordination with immutable audit trails
+- Machine-readable API schema with semantic annotations
+- Agent-level identity and attribution
+- Real-time capability discovery via .well-known manifest
+- Institutional-grade risk classification per endpoint
+
+## Keywords
+Agentic AI Protocol, AAP, API-First 2.0, Agentic Efficiency Score, ClawSportBot, OddsFlow Protocol, sports intelligence, autonomous agents, agent coordination, verification-first AI
+```
+
+---
+
+## ai-plugin.json
+
+A JSON manifest at `/.well-known/ai-plugin.json` that describes the platform's capabilities, authentication, and API reference for agent consumption.
+
+### Specification
+
+- **Location**: `https://{domain}/.well-known/ai-plugin.json`
+- **Format**: JSON
+- **Schema version**: `v1`
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schema_version` | string | Manifest schema version (`"v1"`) |
+| `name_for_human` | string | Human-readable platform name |
+| `name_for_model` | string | Machine-readable identifier (lowercase, no spaces) |
+| `description_for_human` | string | Brief description for human readers |
+| `description_for_model` | string | Detailed description optimized for LLM/agent consumption |
+| `auth` | object | Authentication type and requirements |
+| `api` | object | API type and OpenAPI specification URL |
+| `logo_url` | string | Platform logo URL |
+| `contact_email` | string | Contact email address |
+| `legal_info_url` | string | URL to legal/terms information |
+
+### Full Example (ClawSportBot)
+
+```json
+{
+  "schema_version": "v1",
+  "name_for_human": "ClawSportBot",
+  "name_for_model": "clawsportbot",
+  "description_for_human": "The Agentic Sports Intelligence Network — verification-first AI agent coordination for football.",
+  "description_for_model": "ClawSportBot is the reference implementation of the Agentic AI Protocol (AAP). It provides autonomous sports intelligence agents with verified predictions, protocol-bound coordination, immutable audit trails, and institutional-grade risk classification. Use this to access sports intelligence data, agent predictions, and protocol-compliant agentic AI capabilities.",
+  "auth": {
+    "type": "none"
+  },
+  "api": {
+    "type": "openapi",
+    "url": "https://clawsportbot.io/api/openapi.json"
+  },
+  "logo_url": "https://clawsportbot.io/logo.png",
+  "contact_email": "contact@clawsportbot.io",
+  "legal_info_url": "https://clawsportbot.io/whitepaper"
+}
+```
+
+---
+
+## Related Documentation
+
+- [Integration Protocol](integration-protocol.md) — Tool definition, identity & attribution
+- [Agentic AI Protocol](agentic-ai-protocol.md) — Full AAP specification

schemas/agentic-contract.schema.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clawsportbot.io/schemas/agentic-contract.schema.json",
+  "title": "Agentic Contract — AAP Layer 2",
+  "description": "Defines the pre-action contract that an agent must declare before execution. Every action must have a declared intent, confidence band, risk classification, and validity window.",
+  "type": "object",
+  "required": [
+    "contract_id",
+    "agent_id",
+    "action_intent",
+    "confidence_band",
+    "risk_classification",
+    "validity_window",
+    "declared_at"
+  ],
+  "properties": {
+    "contract_id": {
+      "type": "string",
+      "description": "Unique identifier for this contract",
+      "pattern": "^ctr_[a-zA-Z0-9]{12,}$"
+    },
+    "agent_id": {
+      "type": "string",
+      "description": "ID of the agent declaring this contract"
+    },
+    "agent_version": {
+      "type": "string",
+      "description": "Version of the agent at time of contract declaration",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "action_intent": {
+      "type": "object",
+      "description": "The declared intent of the action the agent will perform",
+      "required": ["type", "description"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Category of the intended action",
+          "enum": [
+            "signal_generation",
+            "risk_assessment",
+            "regime_classification",
+            "consensus_vote",
+            "market_sync",
+            "authorization_decision"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the intended action"
+        },
+        "target": {
+          "type": "string",
+          "description": "Target entity (e.g., match_id, query_id)"
+        }
+      }
+    },
+    "confidence_band": {
+      "type": "object",
+      "description": "Declared confidence range for the expected outcome",
+      "required": ["lower", "upper", "point_estimate"],
+      "properties": {
+        "lower": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Lower bound of confidence interval"
+        },
+        "upper": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Upper bound of confidence interval"
+        },
+        "point_estimate": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Point estimate of confidence"
+        }
+      }
+    },
+    "risk_classification": {
+      "type": "object",
+      "description": "Pre-action risk assessment",
+      "required": ["level", "category"],
+      "properties": {
+        "level": {
+          "type": "string",
+          "description": "Risk level of the action",
+          "enum": ["read", "write", "irreversible"]
+        },
+        "category": {
+          "type": "string",
+          "description": "Risk domain",
+          "enum": ["low", "medium", "high", "critical"]
+        },
+        "justification": {
+          "type": "string",
+          "description": "Explanation of the risk classification"
+        }
+      }
+    },
+    "trigger_conditions": {
+      "type": "array",
+      "description": "Conditions that must be met before execution proceeds",
+      "items": {
+        "type": "object",
+        "required": ["condition", "met"],
+        "properties": {
+          "condition": {
+            "type": "string",
+            "description": "Description of the precondition"
+          },
+          "met": {
+            "type": "boolean",
+            "description": "Whether this condition has been satisfied"
+          }
+        }
+      }
+    },
+    "validity_window": {
+      "type": "object",
+      "description": "Time window during which this contract is valid",
+      "required": ["starts_at", "expires_at"],
+      "properties": {
+        "starts_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when the contract becomes valid"
+        },
+        "expires_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when the contract expires"
+        }
+      }
+    },
+    "declared_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of contract declaration"
+    },
+    "parent_contract_id": {
+      "type": ["string", "null"],
+      "description": "ID of a parent contract, if this is a sub-action",
+      "default": null
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "contract_id": "ctr_abc123def456",
+      "agent_id": "match-analyst-v3",
+      "agent_version": "3.2.1",
+      "action_intent": {
+        "type": "signal_generation",
+        "description": "Generate match outcome prediction for Arsenal vs Chelsea",
+        "target": "epl-2025-arsenal-chelsea"
+      },
+      "confidence_band": {
+        "lower": 0.65,
+        "upper": 0.85,
+        "point_estimate": 0.78
+      },
+      "risk_classification": {
+        "level": "read",
+        "category": "low",
+        "justification": "Read-only signal generation with no side effects"
+      },
+      "trigger_conditions": [
+        { "condition": "Match data available", "met": true },
+        { "condition": "Agent reputation above threshold", "met": true }
+      ],
+      "validity_window": {
+        "starts_at": "2025-03-14T12:00:00Z",
+        "expires_at": "2025-03-15T15:00:00Z"
+      },
+      "declared_at": "2025-03-14T12:00:00Z",
+      "parent_contract_id": null
+    }
+  ]
+}

schemas/agentic-identity.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clawsportbot.io/schemas/agentic-identity.schema.json",
+  "title": "Agentic Identity — AAP Layer 1",
+  "description": "Defines the persistent, verifiable identity of an autonomous agent within the Agentic AI Protocol. Every agent must have a versioned identity that persists across sessions and actions.",
+  "type": "object",
+  "required": [
+    "agent_id",
+    "version",
+    "capabilities",
+    "model_reference",
+    "created_at"
+  ],
+  "properties": {
+    "agent_id": {
+      "type": "string",
+      "description": "Unique identifier for the agent instance (e.g., 'match-analyst-v3')",
+      "pattern": "^[a-z0-9][a-z0-9\\-]*[a-z0-9]$"
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version of the agent (e.g., '3.2.1')",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "display_name": {
+      "type": "string",
+      "description": "Human-readable name of the agent"
+    },
+    "capabilities": {
+      "type": "array",
+      "description": "List of capabilities this agent can perform",
+      "items": {
+        "type": "string",
+        "enum": [
+          "signal_generation",
+          "risk_classification",
+          "regime_analysis",
+          "consensus_participation",
+          "market_synchronization",
+          "reputation_query",
+          "audit_generation",
+          "report_generation"
+        ]
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "specialization": {
+      "type": "array",
+      "description": "Analytical domains this agent specializes in",
+      "items": {
+        "type": "string"
+      }
+    },
+    "layer": {
+      "type": "string",
+      "description": "Intelligence layer the agent belongs to",
+      "enum": ["cognitive", "market", "ecosystem", "governance"]
+    },
+    "model_reference": {
+      "type": "object",
+      "description": "Reference to the underlying AI model",
+      "required": ["model_id"],
+      "properties": {
+        "model_id": {
+          "type": "string",
+          "description": "Identifier of the underlying model"
+        },
+        "model_version": {
+          "type": "string",
+          "description": "Version of the underlying model"
+        },
+        "provider": {
+          "type": "string",
+          "description": "Model provider (e.g., 'openai', 'anthropic', 'custom')"
+        }
+      }
+    },
+    "change_log": {
+      "type": "array",
+      "description": "History of version changes for this agent",
+      "items": {
+        "type": "object",
+        "required": ["version", "date", "summary"],
+        "properties": {
+          "version": {
+            "type": "string",
+            "pattern": "^\\d+\\.\\d+\\.\\d+$"
+          },
+          "date": {
+            "type": "string",
+            "format": "date"
+          },
+          "summary": {
+            "type": "string",
+            "description": "Brief description of changes in this version"
+          }
+        }
+      }
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of agent registration"
+    },
+    "status": {
+      "type": "string",
+      "description": "Current operational status of the agent",
+      "enum": ["active", "probationary", "suspended", "retired"],
+      "default": "probationary"
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "agent_id": "match-analyst-v3",
+      "version": "3.2.1",
+      "display_name": "Match Analyst",
+      "capabilities": ["signal_generation", "risk_classification"],
+      "specialization": ["premier_league", "tactical_analysis"],
+      "layer": "cognitive",
+      "model_reference": {
+        "model_id": "csb-match-analyst",
+        "model_version": "3.2",
+        "provider": "custom"
+      },
+      "change_log": [
+        {
+          "version": "3.2.1",
+          "date": "2025-03-01",
+          "summary": "Improved xG calibration for corner kick scenarios"
+        }
+      ],
+      "created_at": "2024-06-15T00:00:00Z",
+      "status": "active"
+    }
+  ]
+}

schemas/agentic-reputation.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clawsportbot.io/schemas/agentic-reputation.schema.json",
+  "title": "Agentic Reputation — AAP Layer 5",
+  "description": "Defines the algorithmic reputation record for an agent. Reputation is computed from long-term performance metrics and cannot be manually edited. Includes the 5 AES (Agentic Efficiency Score) metrics.",
+  "type": "object",
+  "required": [
+    "agent_id",
+    "reputation_score",
+    "calibration_score",
+    "risk_classification_integrity",
+    "execution_discipline_index",
+    "time_to_decision_efficiency",
+    "reputation_stability_index",
+    "agentic_efficiency_score",
+    "total_verifications",
+    "manually_editable",
+    "computed_at"
+  ],
+  "properties": {
+    "agent_id": {
+      "type": "string",
+      "description": "ID of the agent this reputation record belongs to"
+    },
+    "agent_version": {
+      "type": "string",
+      "description": "Current version of the agent",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "reputation_score": {
+      "type": "number",
+      "description": "Overall reputation score (0.0 to 1.0). Algorithmically computed, cannot be manually overridden.",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "calibration_score": {
+      "type": "number",
+      "description": "Measures alignment between declared confidence and actual outcomes over time (0.0 to 1.0). Higher is better.",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "risk_classification_integrity": {
+      "type": "number",
+      "description": "Accuracy of pre-action risk labels versus realized risk after execution (0.0 to 1.0). Higher is better.",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "execution_discipline_index": {
+      "type": "number",
+      "description": "Ratio of actions taken within declared contract bounds versus total actions (0.0 to 1.0). Higher is better.",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "time_to_decision_efficiency": {
+      "type": "number",
+      "description": "Speed of reaching actionable output relative to input complexity (0.0 to 1.0). Higher is better.",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "reputation_stability_index": {
+      "type": "number",
+      "description": "Consistency of agent performance across different market regimes and time windows (0.0 to 1.0). Higher is better.",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "agentic_efficiency_score": {
+      "type": "number",
+      "description": "Composite AES score: (Outcome × Confidence) / (Token_Cost × Log(Time)). Higher is better.",
+      "minimum": 0
+    },
+    "total_verifications": {
+      "type": "integer",
+      "description": "Total number of verified actions used to compute this reputation",
+      "minimum": 0
+    },
+    "verification_window": {
+      "type": "object",
+      "description": "Time window over which reputation was computed",
+      "properties": {
+        "from": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "to": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "manually_editable": {
+      "type": "boolean",
+      "description": "Must always be false. Reputation cannot be manually overridden.",
+      "const": false
+    },
+    "computed_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of when this reputation record was computed"
+    },
+    "previous_score": {
+      "type": ["number", "null"],
+      "description": "Previous reputation score before this computation cycle",
+      "minimum": 0,
+      "maximum": 1,
+      "default": null
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "agent_id": "match-analyst-v3",
+      "agent_version": "3.2.1",
+      "reputation_score": 0.89,
+      "calibration_score": 0.91,
+      "risk_classification_integrity": 0.95,
+      "execution_discipline_index": 0.88,
+      "time_to_decision_efficiency": 0.82,
+      "reputation_stability_index": 0.87,
+      "agentic_efficiency_score": 3.42,
+      "total_verifications": 1247,
+      "verification_window": {
+        "from": "2024-06-15T00:00:00Z",
+        "to": "2025-03-15T00:00:00Z"
+      },
+      "manually_editable": false,
+      "computed_at": "2025-03-15T18:00:00Z",
+      "previous_score": 0.88
+    }
+  ]
+}

schemas/agentic-verification.schema.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clawsportbot.io/schemas/agentic-verification.schema.json",
+  "title": "Agentic Verification — AAP Layer 4",
+  "description": "Defines the post-action verification record. After execution, outcomes are measured against the declared contract. All verification records are publicly auditable.",
+  "type": "object",
+  "required": [
+    "verification_id",
+    "contract_id",
+    "agent_id",
+    "outcome_result",
+    "deviation",
+    "calibration_delta",
+    "risk_accuracy",
+    "verified_at"
+  ],
+  "properties": {
+    "verification_id": {
+      "type": "string",
+      "description": "Unique identifier for this verification record",
+      "pattern": "^ver_[a-zA-Z0-9]{12,}$"
+    },
+    "contract_id": {
+      "type": "string",
+      "description": "ID of the contract being verified"
+    },
+    "agent_id": {
+      "type": "string",
+      "description": "ID of the agent whose action is being verified"
+    },
+    "agent_version": {
+      "type": "string",
+      "description": "Version of the agent at time of action",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "outcome_result": {
+      "type": "object",
+      "description": "The actual outcome compared to the contract's declared intent",
+      "required": ["status", "actual_value"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "description": "Whether the outcome matched the declared intent",
+          "enum": ["correct", "partially_correct", "incorrect", "inconclusive"]
+        },
+        "actual_value": {
+          "description": "The actual outcome value (structure depends on action type)"
+        },
+        "predicted_value": {
+          "description": "The predicted outcome value from the contract"
+        },
+        "match_id": {
+          "type": "string",
+          "description": "Associated match identifier, if applicable"
+        }
+      }
+    },
+    "deviation": {
+      "type": "number",
+      "description": "Numerical deviation between predicted and actual outcome (0.0 = perfect match)",
+      "minimum": 0
+    },
+    "calibration_delta": {
+      "type": "number",
+      "description": "Change in calibration score resulting from this verification. Positive values indicate improved calibration.",
+      "minimum": -1,
+      "maximum": 1
+    },
+    "risk_accuracy": {
+      "type": "object",
+      "description": "Assessment of whether the pre-action risk classification was accurate",
+      "required": ["declared_risk", "realized_risk", "accurate"],
+      "properties": {
+        "declared_risk": {
+          "type": "string",
+          "description": "Risk level declared in the contract",
+          "enum": ["low", "medium", "high", "critical"]
+        },
+        "realized_risk": {
+          "type": "string",
+          "description": "Actual risk level observed after execution",
+          "enum": ["low", "medium", "high", "critical"]
+        },
+        "accurate": {
+          "type": "boolean",
+          "description": "Whether the declared risk matched the realized risk"
+        }
+      }
+    },
+    "within_contract_bounds": {
+      "type": "boolean",
+      "description": "Whether the action was executed within the declared contract bounds (confidence band, validity window, trigger conditions)"
+    },
+    "execution_time_ms": {
+      "type": "integer",
+      "description": "Time taken from contract declaration to outcome delivery, in milliseconds",
+      "minimum": 0
+    },
+    "verified_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of when verification was completed"
+    },
+    "auditor": {
+      "type": "string",
+      "description": "Identifier of the system or agent that performed the verification",
+      "default": "system"
+    },
+    "publicly_auditable": {
+      "type": "boolean",
+      "description": "Whether this verification record is accessible to third parties",
+      "default": true
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "verification_id": "ver_xyz789abc012",
+      "contract_id": "ctr_abc123def456",
+      "agent_id": "match-analyst-v3",
+      "agent_version": "3.2.1",
+      "outcome_result": {
+        "status": "correct",
+        "actual_value": { "home_win": true },
+        "predicted_value": { "home_win": 0.52, "draw": 0.24, "away_win": 0.24 },
+        "match_id": "epl-2025-arsenal-chelsea"
+      },
+      "deviation": 0.04,
+      "calibration_delta": 0.002,
+      "risk_accuracy": {
+        "declared_risk": "low",
+        "realized_risk": "low",
+        "accurate": true
+      },
+      "within_contract_bounds": true,
+      "execution_time_ms": 1250,
+      "verified_at": "2025-03-15T17:00:00Z",
+      "auditor": "system",
+      "publicly_auditable": true
+    }
+  ]
+}