# 🚀 ai-ready-docs: The Standard for AI-Native Documentation

[![AIRD Compliant](https://img.shields.io/badge/AI--Ready-Docs-v1.2-gold)](https://github.com/iwweee/ai-ready-docs)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://spdx.org/licenses/mit.html)

**Stop writing documentation for humans. Start building APIs for LLMs.**

`ai-ready-docs` (AIRD) is a rigorous specification designed to transform documentation from "human-readable text" into "**AI-consumable interfaces**." 

In the era of Agentic Workflows, the bottleneck is no longer the model's reasoning power, but the **quality and structure of the context** and the **precision of the execution paths** provided. AIRD v1.2 eliminates ambiguity, minimizes token waste, and transforms documentation into a direct driver for autonomous AI agents.

---

## 📊 The AIRD Advantage

| Dimension | Traditional Docs (Human-Centric) | AIRD Standard (AI-Native) |
| :--- | :--- | :--- |
| **Discovery** | Manual search / Random crawling | $\text{L1 Discovery} \rightarrow$ Instant mapping via `llms.txt` |
| **Parsing** | Heuristic chunking (Unpredictable) | $\text{L2 Structure} \rightarrow$ Deterministic hierarchy |
| **Cognition** | Reliance on LLM's general knowledge | $\text{L3 Context} \rightarrow$ Explicit `ai-context` blocks |
| **Maintenance** | Manual updates $\rightarrow$ Doc drift | $\text{L4 Evolution} \rightarrow$ Closed-loop `.ai-feedback` |
| **Execution** | Vague instructions $\rightarrow$ Hallucinations | $\text{L5 Actionable} \rightarrow$ Deterministic Execution Protocols |

---

## 🏗️ The 5-Layer Protocol (AIRD Spec v1.2)

### 📡 L1: Discovery (The Map)
**Goal**: Immediate orientation via `llms.txt`.

### 🏗️ L2: Structure (The Skeleton)
**Goal**: Perfect chunking via strict hierarchy and deterministic naming.

### 🧠 L3: Context (The Brain)
**Goal**: Eliminate assumptions using `ai-context` blocks (Topic, Prerequisites, Warnings).

### 🔄 L4: Evolution (The Loop)
**Goal**: Continuous self-improvement via the `.ai-feedback.md` mechanism.

### ⚡ L5: Actionable (The Protocol) $\leftarrow$ NEW
**Goal**: Move from "Information Retrieval" to "Autonomous Execution" via `## Execution Protocol`.

---

## 🛠️ Getting Started (The Fast Track)

### 1. 📚 Learn by Example
Don't start from scratch. Copy our proven AIRD templates for different scenarios:
👉 **[Explore the Examples Gallery](./examples/)**
- **Python Lib**: Ideal for SDKs and utility tools.
- **System Architecture**: Best for complex enterprise software.
- **Agent SOP**: Perfect for AI-driven workflows.

### 2. 📈 Measure Your "AI-Readiness"
Run our advanced Linter to get a quantitative **AI-Ready Score (0-100)** and a detailed compliance report.
```bash
# Install/Download aird_lint_v5.py
python aird_lint_v5.py --suggest ./your-docs-folder
```
*The linter now checks for broken semantic dependencies and calculates your readiness rank (Elite $\rightarrow$ Low).*

### 3. 🔄 Operationalize the Evolutionary Loop
Stop manually fixing docs. Implement the L4 evolutionary workflow where AI failures drive automated PRs for documentation updates.
👉 **[Read the Feedback Workflow Guide](./FEEDBACK_WORKFLOW.md)**

### 4. 🤖 Mastering Agentic Execution
Learn how to implement L5 protocols to turn your docs into an autonomous agent's operational manual.
👉 **[Read the Agentic Guide](./L5_AGENTIC_GUIDE.md)**

### 5. 📜 Detailed Specification
For a deep dive into the technical requirements of each layer:
👉 **[Read the Full SPEC.md](./AIRD_SPEC.md)**

---

## 🌟 Adoption & Ecosystem

We are building a world where every project is `AI-Ready`.

- **Current Status**: v1.2 (Agentic Stage)
- **Goal**: To become the default documentation layer for autonomous AI agents.

If you've implemented AIRD in your project, please let us know or open a PR to be added to our **AIRD-Compliant Projects** list!

---

## 📄 License
Distributed under the MIT License. See `LICENSE` for more information.