Version 1.0.0 · MIT License · Open Standard

📖 Read the article on Medium — AI Is Now the Primary Reader of Your Docs. Nobody Told Your Docs. 📚 Full documentation — specification, writing guide, examples, ecosystem 📄 Position paper — DOI: 10.5281/zenodo.19019719 👤 Author: Nikša Barlović — ORCID: 0009-0004-7421-0913

HADS is a lightweight convention for writing technical documentation that works equally well for humans and AI language models — with AI as the primary consumer.

It is not a new file format. It is a set of tagging and structural rules applied to standard Markdown. Any editor renders it. Any AI reads it. No tooling required.

Technical documentation is increasingly read by AI models before humans ever see it. Models are used to look up APIs, understand file formats, debug errors, generate code. But documentation is written for humans — verbose, contextual, narrative.

This creates waste:

• AI consumes thousands of tokens to extract a handful of facts
• Smaller / local models lose context and hallucinate
• Humans still need the context that AI wants to skip

HADS solves this by separating signal from context — in the same document, without duplication.

Every block in a HADS document is tagged with its intended reader:

AI instruction at the top of every HADS document tells the model what to read and what to skip. This is the key innovation: the document teaches the model how to read it.

• Small / local models — can extract facts without reading everything
• Large models — spend fewer tokens, reduce hallucination risk
• Developers — write once, serves both audiences
• Teams — single source of truth, no separate "AI context" files
• Open source projects — documentation that AI coding assistants actually use correctly

Best measured example from the current benchmark corpus. AI loads only what it needs.

The rest stays in the file for humans. One source. No duplication.

## Authentication **[SPEC]** - Method: Bearer token - Header: `Authorization: Bearer <token>` - Token expiry: 3600 seconds - Refresh endpoint: `POST /auth/refresh` **[NOTE]** Tokens were originally session-based (pre-v2.0). If you see legacy docs mentioning cookie auth, ignore them. The switch happened in 2022 when the API went public. Refresh tokens do not expire but can be revoked. **[BUG] Token silently rejected after password change** Cause: All tokens invalidated on password change, no error returned. Symptom: 401 with body `{"error": "invalid_token"}` — identical to expired token. Fix: Re-authenticate and store new token. Check for 401 after any account operation.

An AI reading this extracts: method, header format, expiry, refresh endpoint — in one [SPEC] block. A human reads the [NOTE] and understands history and context. Both read the [BUG].

hads/ ├── README.md — this file ├── SPEC.md — full formal specification ├── case-studies/ │ └── polymarket-bot.md — production AI agent codebase (48% token reduction) ├── examples/ │ ├── api-reference.md — REST API documentation example │ ├── file-format.md — binary file format example │ └── configuration.md — configuration system example ├── validator/ │ └── validate.py — validates a Markdown file against HADS spec └── LICENSE 

Real-world measurements of HADS applied to production codebases:

• Polymarket trading bot — 705-line CLAUDE.md for an autonomous trading agent. 48% of context was version history loaded on every session. Tagging saves ~39% per typical session.

1. Read SPEC.md — the full standard (15 min)
2. Look at examples/ — real documents in HADS format
3. Run the validator on your own docs: python validator/validate.py your-doc.md

A Fermi estimate of what HADS adoption would mean globally:

Assumptions:

• ~1 billion AI queries/day touching technical docs (50M developers × 10 queries/day + enterprise agents, CI/CD pipelines, support bots)
• HADS reduces tokens read per query by 7.91–36.68% across the current example corpus — 24.34% average SPEC-only reduction, with the best current measured example at 36.68%
• Energy cost: ~0.003 Wh per 1,000 tokens (GPT-4 class inference)
• Time saved: ~2 min/query from more precise first answers and fewer follow-ups

Annual savings at full adoption:

At 10% adoption these numbers drop proportionally — still ~$60B/year in recovered productivity.

The point: structuring documentation for AI consumption is economically material at global scale, even before accounting for better code quality from more accurate AI answers.

hads-skills — AI skills for converting documents to HADS format. Works with Claude Code, any model via system prompt, or zero-setup paste-and-run.

HADS is an open standard. Contributions welcome:

• New block types (open an issue first)
• Additional examples
• Validator improvements
• Ports of the validator to other languages

Please read SPEC.md before contributing — especially the design principles section.

MIT. Use freely, commercially or otherwise. Attribution appreciated but not required.

HADS exists because documentation should serve everyone who reads it — human or machine.