# Linten — Complete Specification & Documentation

> The definitive developer tool suite for validating, scaffolding, and optimizing official llms.txt and llms-full.txt files. Engineered by Loopstates.

---

## 1. What is llms.txt?

The `llms.txt` standard (proposed at https://llmstxt.org) provides AI agents (such as ChatGPT, Claude, Perplexity, and local coding assistants) with a clean, structured, and curated index of documentation when crawling or retrieving context from a website or developer documentation portal.

### Standard Anatomy
A valid `llms.txt` file must adhere to the following structure:
1. **Single H1 Title**: `# Project Name`
2. **Blockquote Summary**: `> Concise project description`
3. **Structured Sections**: `## Documentation`, `## Guides`, `## Optional`
4. **Link Pattern**: Bulleted list where each entry follows `- [Title](URL): Description`
5. **Companion File**: An optional companion file named `llms-full.txt` containing complete, concatenated markdown for all linked pages.

---

## 2. Linten Feature Capabilities

### AST Spec Validation
Linten performs structural parsing of `llms.txt` files to ensure compliance with the official specification:
- Enforces single H1 header.
- Validates presence of mandatory summary blockquote.
- Verifies section headings and grouping.
- Probes link anchor text, URLs, and descriptive summaries.

### Deep Link Health Probing
Linten scans every hyperlink defined in the document (up to 250 links per execution):
- Detects 200 OK endpoints.
- Identifies 301/302 redirects and warns if they should point to the canonical URL.
- Flags 404 Not Found broken links.
- Warns against 403 Forbidden links blocked by bot-detection WAFs (e.g., Cloudflare, Akamai).

### Multi-Model Context Window Budgeting
Linten estimates the exact token footprint of both `llms.txt` and `llms-full.txt`:
- **GPT-4o**: 128k context window load percentage.
- **Claude 3.5 Sonnet**: 200k context window sizing and attention degradation warnings.
- **Gemini 1.5 Pro**: 1M+ context window sizing.
- **Index Bloat Prevention**: Warns if a primary `llms.txt` exceeds ~2,500 tokens (which degrades initial crawler retrieval latency).

### Companion llms-full.txt Synthesizer
Linten crawls all documentation links listed in `llms.txt` via clean markdown extraction and compiles an aggregated `llms-full.txt` companion file with proper delimiters and headers.

### Dynamic GitHub README Badges
Linten provides a dynamic SVG Shields badge endpoint:
```markdown
[![llms.txt](https://linten.apps.loopstates.com/badge?domain=YOUR_DOMAIN&score=100)](https://loopstates.com)
```

---

## 3. Cloud API Endpoints

All endpoints are hosted on Vercel Edge/Serverless infrastructure with HMAC-SHA256 client authentication and sliding-window DDoS rate limiting.

### GET /api/v1/validate
Audits a live URL.
- **Query Params**: `url` (string, required)
- **Response**: JSON containing overall score, sub-scores, link health stats, token estimates, and detailed findings.

### POST /api/v1/validate
Validates pasted `llms.txt` raw markdown content.
- **Body**: `{ "content": "string" }`

### GET /api/v1/generate
Scaffolds a starter `llms.txt` file from an existing website.
- **Query Params**: `url` (string, required)

### POST /api/v1/synthesize
Compiles an aggregated `llms-full.txt` companion from `llms.txt` content or live domain.
- **Body / Query**: `url` or `{ "content": "string" }`

### GET /badge
Returns a dynamic SVG badge for GitHub READMEs.
- **Query Params**: `domain` (string), `score` (optional integer)

---

## 4. Ecosystem & Clients

- **VS Code Extension**: In-editor squiggles for syntax and broken links, status bar score indicator, QuickFix CodeActions, and companion file synthesis.
- **Obsidian Community Plugin**: Ribbon icon, audit score modal, auto-validate on save, and digital garden generator.

---

## 5. Publisher Information

Linten is engineered and maintained by **Loopstates** (https://loopstates.com).
Loopstates builds high-performance developer tooling and AI infrastructure.