1# LLM Format Output Reference
2 
3## Overview
4 
5The `--format llm` output is a compact, token-optimized hybrid XML/text format designed specifically for AI agent consumption. It provides structured audit data in a format that balances machine readability with token efficiency.
6 
7## Key Characteristics
8 
9- **40-70% smaller** than verbose XML format
10- **1-space indentation** for minimal token usage
11- **Hybrid structure**: XML tags + text prefixes for metadata
12- **Inline attributes**: Metadata stored as XML attributes, not nested elements
13- **Comma-separated lists**: Pages and arrays formatted inline
14- **Flattened hierarchy**: Reduced nesting depth compared to verbose XML
15 
16## Format Structure
17 
18### 1. Document Header
19 
20```xml
21<?xml version="1.0" encoding="UTF-8"?>
22<audit version="0.0.24">
23```
24 
25### 2. Site Information
26 
27```xml
28<site url="https://example.com" crawled="51" date="2025-01-18T10:30:00Z"/>
29```
30 
31Attributes:
32- `url` - Base URL audited
33- `crawled` - Number of pages crawled
34- `date` - ISO 8601 timestamp
35 
36### 3. Health Score
37 
38```xml
39<score overall="85" grade="B">
40 <cat name="Core SEO" score="92"/>
41 <cat name="Technical SEO" score="88"/>
42 <cat name="Content Quality" score="76"/>
43</score>
44```
45 
46Attributes:
47- `overall` - 0-100 health score
48- `grade` - Letter grade (A-F)
49- Categories with individual scores
50 
51### 4. Summary
52 
53```xml
54<summary passed="120" warnings="15" failed="8"/>
55```
56 
57Attributes:
58- `passed` - Number of passed checks
59- `warnings` - Number of warnings
60- `failed` - Number of failed checks
61 
62### 5. Issues Section
63 
64Issues are grouped by category with compact inline metadata:
65 
66```xml
67<issues>
68 <category name="Core SEO" errors="2" warnings="3">
69  <rule id="core/meta-title" severity="error" status="fail">
70   Missing or empty meta title tags
71   Desc: Every page should have a unique meta title
72   Fix: Add descriptive <title> tags to each page
73   Pages (2): https://example.com/about, https://example.com/contact
74   Items (2):
75    - https://example.com/about
76    - https://example.com/contact
77  </rule>
78  <rule id="core/meta-description" severity="warning" status="warn">
79   Desc: Pages should have meta descriptions
80   Fix: Add <meta name="description"> tags
81   Pages (5): https://example.com/page1, https://example.com/page2, ...
82  </rule>
83 </category>
84 <category name="Performance" errors="0" warnings="1">
85  ...
86 </category>
87</issues>
88```
89 
90#### Rule Structure
91 
92Each `<rule>` element contains:
93 
94**Attributes:**
95- `id` - Rule identifier (e.g., `core/meta-title`)
96- `severity` - `error`, `warning`, or `info`
97- `status` - `pass`, `warn`, or `fail`
98 
99**Text Content (in order):**
1001. **Message** (optional) - Human-readable issue summary
1012. **Desc:** - Rule description (what's being checked)
1023. **Fix:** - Recommended solution (how to fix)
1034. **Pages (n):** - Comma-separated list of affected URLs
1045. **Items (n):** - Dash-prefixed list of specific items with metadata
105 
106### 6. Items Format
107 
108Items provide detailed context about affected elements:
109 
110```xml
111Items (3):
112 - https://example.com/missing-title (title: "")
113 - https://example.com/duplicate-title (title: "Home Page") (from: https://example.com/other)
114 - /broken-link [status: 404, type: internal] (from: https://example.com/contact)
115```
116 
117Item format:
118- `- <id>` - Primary identifier (URL, selector, etc.)
119- `(<label>)` - Optional human-readable label if different from id
120- `[key: value, ...]` - Metadata in square brackets
121- `(from: <sources>)` - Source pages where item appears
122 
123## Diff Output (LLM Format)
124 
125When using `squirrel report --diff` or `--regression-since` with `--format llm`,
126the output is a compact XML diff format:
127 
128```xml
129<?xml version="1.0" encoding="UTF-8"?>
130<diff version="0.0.24">
131 <baseline id="a7b3c2d1" url="https://example.com" date="2026-01-17T10:30:00Z" pages="42" score="87" grade="B"/>
132 <current id="b9c4e1f2" url="https://example.com" date="2026-01-18T10:30:00Z" pages="44" score="84" grade="B"/>
133 <summary added="3" removed="1" changed="2" regressions="1" improvements="1"/>
134 <added>
135  <issue fp="abc123" rule="core/meta-title" severity="error" status="fail" check="meta-title" category="core" weight="8">
136   Missing page title
137   Target: page /about
138  </issue>
139 </added>
140 <removed>
141  ...
142 </removed>
143 <changed>
144  <change type="regression" fp="def456" rule="links/broken-links" severity="warning" status="fail" check="broken-links">
145   warn→fail: Broken link count increased
146   Before:
147    <issue ...> ... </issue>
148   After:
149    <issue ...> ... </issue>
150  </change>
151 </changed>
152</diff>
153```
154 
155Key fields:
156- `fp`: deterministic fingerprint for the issue instance
157- `rule`, `check`, `severity`, `status`: rule and check metadata
158- `Target:`: item/page/check target
159- `change type`: `regression`, `improvement`, or `change`
160 
161## Example Output
162 
163```xml
164<?xml version="1.0" encoding="UTF-8"?>
165<audit version="0.0.24">
166<site url="https://example.com" crawled="51" date="2025-01-18T10:30:00Z"/>
167<score overall="78" grade="C">
168 <cat name="Core SEO" score="85"/>
169 <cat name="Technical SEO" score="92"/>
170 <cat name="Performance" score="65"/>
171</score>
172<summary passed="98" warnings="12" failed="5"/>
173<issues>
174 <category name="Core SEO" errors="2" warnings="1">
175  <rule id="core/meta-title" severity="error" status="fail">
176   Missing meta title on 2 pages
177   Desc: Every page should have a unique meta title
178   Fix: Add descriptive <title> tags to each page
179   Pages (2): https://example.com/about, https://example.com/contact
180   Items (2):
181    - https://example.com/about
182    - https://example.com/contact
183  </rule>
184 </category>
185</issues>
186</audit>
187```
188 
189## Usage
190 
191The LLM format is available via both `audit` and `report` commands:
192 
193```bash
194# Direct LLM output (single step)
195squirrel audit https://example.com --format llm
196 
197# Or two-step workflow
198squirrel audit https://example.com
199squirrel report <audit-id> --format llm
200 
201# Pipe directly to AI agent
202squirrel audit https://example.com --format llm | claude
203```
204 
205The `audit` command supports `--format llm` directly for convenience. Use the two-step workflow when you need to generate reports in multiple formats from a single audit.
206 
207## Comparison with Other Formats
208 
209| Format | Size | Structure | Best For |
210|--------|------|-----------|----------|
211| `xml` | 209KB | Verbose, 2-space indent, fully nested | Enterprise integration, archival |
212| `llm` | 125KB | Compact, 1-space indent, hybrid | AI agents, token-limited contexts |
213| `json` | 180KB | Structured data | Programmatic processing |
214| `text` | 45KB | Plain text, no structure | Simple piping, grep |
215 
216## Token Efficiency
217 
218The LLM format achieves 40-70% size reduction compared to verbose XML through:
219 
2201. **1-space indentation** instead of 2-4 spaces
2212. **Inline attributes** instead of nested elements
2223. **Text prefixes** (Desc:, Fix:) instead of XML tags
2234. **Comma-separated lists** instead of multiple elements
2245. **Flattened hierarchy** - fewer nesting levels
225 
226## XML Character Escaping
227 
228Special characters are properly escaped:
229- `&` → `&amp;`
230- `<` → `&lt;`
231- `>` → `&gt;`
232- `"` → `&quot;`
233- `'` → `&apos;`
234 
235## Design Philosophy
236 
237The LLM format is optimized for:
2381. **Token efficiency** - Critical for API cost and context limits
2392. **Easy parsing** - XML structure for reliable extraction
2403. **Human readability** - AI agents can explain issues naturally
2414. **Progressive disclosure** - Summary → Categories → Rules → Items
2425. **Actionable insights** - Fix recommendations included inline
243 
244## Implementation Notes
245 
246- Generated by `generateLlmReport()` in `app/src/reports/output/llm.ts`
247- Empty issues section renders as self-closing: `<issues/>`
248- All text content is XML-escaped for safety
249- Indentation uses spaces only (no tabs)
250- Line endings are Unix-style (`\n`)
251