# llm-files Full Instructions

## LLM Files Purpose

LLM files (`llms.txt` and `llms-full.txt`) are structured content manifests for AI/LLM crawlers. They provide curated, structured information about Ordio's most important pages to help AI systems discover, understand, and cite content.

## File Structure Requirements

### Required Components

1. **H1 Title**: `# Ordio`
2. **Base URL**: `https://www.ordio.com`
3. **Header Metadata**: Version, dates, language, region, purpose, Content-Tiefe (Quality Signals)
4. **Blockquote Summary**: Brief site description
5. **H2 Sections**: Categorized content groups (17 standard sections)
6. **Entry Format**: Structured entries with metadata and URLs
7. **Häufige Nutzerfragen**: FAQ format `? "question" → url`; target 10–15 high-intent queries; use canonical URLs

### Section Ordering

Standard sections (in order):

1. Wichtigste Ressourcen (Pillar Pages)
2. Sofort-Lösungen (Immediate Solutions)
3. Kernfunktionen (Core Features)
4. Branchenlösungen (Industry Solutions)
5. Tools & Rechner
6. Vorlagen & Downloads
7. Alternativen & Vergleiche
8. Ratgeber & Wissen
9. Blog & Insights
10. Downloads & Ressourcen
11. Unternehmen
12. Kontakt & Support
13. Technische Informationen
14. Sitemaps & Crawler Access
15. Semantische Keywords & Entitäten
16. Content Qualitätsindikatoren
17. Häufige Nutzerfragen

## Entry Format Requirements

### Standard Format

```
> [TYPE: Metadata | Tags] Title - Description (Action) context (Context) advantage (Advantage) outcome (Outcome)
https://www.ordio.com/url
```

### Required Components

1. **Type Tag**: `[TYPE: Metadata | Tags]`
  - **Blog content (ARTICLE, LEXIKON, GUIDE):** Use `[LEXIKON: YYYY-MM-DD | X Min | N Wörter]`, `[GUIDE: YYYY-MM-DD | X Min | N Wörter]`, `[ARTICLE: YYYY-MM-DD | Inside Ordio | X Min | N Wörter]` when read time/word count available; omit metadata segment when unavailable. Omit CategoryLabel when TYPE implies it.
  - **Non-blog:** `[PRODUCT: Cloud | Mobile Apps | Priority]`, `[GUIDE: X Min Read | Pillar | Umfassend]` (pillar pages), `[CALCULATOR: Instant | Kostenlos | Top]`
  - **Category/Overview pages:** `[CATEGORY: Name | Count | Description]` (e.g. `[CATEGORY: Lexikon | 85 Artikel | Fachbegriffe]`); `[LEXIKON: N Begriffe | Nachschlagewerk]` for Lexikon overview
  - **Spec note:** Ordio extends the llms.txt spec (llmstxt.org) with blockquote-style entries, TYPE tags, and ACAO framework for GEO/AEO optimization. The extension is intentional; see LLM_FILES_GUIDE.md Spec Compliance section.
2. **Title**: Brief, descriptive title
3. **Description**: Full description following ACAO framework
4. **ACAO Framework**:
  - **(Action)** - What the user does
  - **(Context)** - Background/conditions
  - **(Advantage)** - Benefits/value
  - **(Outcome)** - Measurable results
5. **URL**: Absolute URL with trailing slash for directory URLs

### ACAO Framework Requirements

**CRITICAL**: Every entry MUST include all four ACAO components:

- **(Action)**: What action the user takes
- **(Context)**: Background/conditions/audience
- **(Advantage)**: Benefits/value proposition
- **(Outcome)**: Measurable results/success metrics

**Example**:

```
> [PRODUCT: Cloud | Mobile Apps | Priority] Schichtplan - Erstelle optimierte Dienstpläne (Action) für Gastronomie, Einzelhandel und Pflege (Context) mit Ordio's cloudbasierter Schichtplanungs-Software in 50% weniger Zeit (Advantage) und reduziere Planungsfehler um 80% bei über 1.700 zufriedenen Kunden (Outcome)
https://www.ordio.com/schichtplan
```

## Content Guidelines

### Semantic Richness Requirements

**ALWAYS include**:

- **Entity mentions**: Company names (Ordio), product names, locations (Deutschland, DACH-Region)
- **Metrics**: Customer counts (1.700+ Kunden), article counts (99+ Artikel), time savings (50% weniger Zeit)
- **Comparative facts**: Industry-specific data, legal compliance info
- **Specific details**: Platform info (iOS & Android), integrations (DATEV, Personio)

### GEO/AEO Optimization

**For key entries**:

- **Answer-ready**: 40-60 words for important entries
- **Question-answer format**: Include "who, what, when, where, why" elements
- **Excerptable**: Make descriptions standalone and quotable
- **Structured data alignment**: Match schema markup on pages

### Blog Entry Dates

**Use the more recent of publication_date and modified_date** for blog/article entries. This signals content freshness to AI crawlers (SEO/AEO/GEO best practice). Do not falsify dates; only reflect actual updates.

### Date Management

**CRITICAL**: Always use current date:

- Check current date: `date +%Y-%m-%d`
- Update "Last Updated" dates monthly
- Update year references (e.g., "für Deutschland 2026")
- Never use placeholder dates

## URL Requirements

### Character Encoding

- **UTF-8 only**: Files must be UTF-8. `.htaccess` sets `AddDefaultCharset UTF-8` and explicit `Content-Type: text/plain; charset=utf-8` for llms.txt/llms-full.txt to prevent mojibake (e.g. `für` → `für`).

### Format Standards

- **Absolute URLs**: Always use `https://www.ordio.com/...`
- **Trailing slashes**: **Use exactly the canonical form used on the live site and in `html/llms*.txt` for that resource** (do not duplicate the same path with and without a slash). Pillar Insights URLs are typically **without** a trailing slash (e.g. `/insights/dienstplan`, `/insights/zeiterfassung`). Many blog post URLs in the full file use a **trailing slash** (e.g. `/insights/lexikon/begriff/`). Product and tool paths have **no** trailing slash (e.g. `/schichtplan`, `/tools/brutto-netto-rechner`).
- **No trailing slashes**: For “leaf” marketing routes that are not blog slugs (e.g. `/schichtplan`, `/payroll`, `/preise`).
- **Consistency**: Match sitemap entries and avoid two variants of the same URL in one file.

### Validation

**Periodic only** (script fetches each URL; can take 30+ minutes):

- Run URL validator occasionally: `python3 v2/scripts/llms/validate-llms-urls.py --file both`
- Do **not** run during new blog creation – too slow. Do **not** run on every sync or commit.
- Use monthly/quarterly or before major releases.

## File Differences

### llms.txt (Essentials)

- **Purpose**: Quick AI access, featured snippets, voice search
- **Size**: ~80 URLs (curated)
- **Content**: Top products, top industries, top tools, top guides
- **Update Frequency**: Monthly
- **Focus**: Quality over quantity, high-value content only

### llms-full.txt (Comprehensive)

- **Purpose**: Complete AI context, comprehensive research
- **Size**: ~550–600+ unique URLs (full blog + hubs; re-count after large syncs)
- **Content**: All products, all industries, all tools, all blog posts
- **Update Frequency**: Monthly
- **Focus**: Complete coverage, all pages and content

### Count Drift Troubleshooting

If `validate-llms-metadata.py --report` reports Lexikon/Ratgeber mismatches: run `php v2/scripts/llms/sync-blog-posts-to-llms.php --update-counts` to auto-update headers, or manually update Content-Tiefe and [CATEGORY: ...] entries to match validator output.

## Maintenance Requirements

### Update Frequency

- **Monthly**: Review and update dates
- **Quarterly**: Full content audit, add/remove entries
- **As needed**: When new high-value pages are published

### Product Updates Pages

**CRITICAL**: Product update pages use a **manual review process**. Do NOT use automated generation.

**Process:**

1. User notifies when new pages are published
2. AI reviews each page individually using checklist
3. Determines inclusion (llms.txt vs llms-full.txt)
4. Creates optimized entry with ACAO framework
5. Adds to appropriate file(s)

**Inclusion Criteria:**

- **llms.txt**: Main page + current month + last 2 months + top 3 features per month
- **llms-full.txt**: All month pages + all feature posts with `read_more_link`

**Documentation:** See `docs/systems/product-updates/PRODUCT_UPDATES_LLMS_PROCESS.md` for complete workflow.

### Pre-Update Checklist

- Check current date: `date +%Y-%m-%d`
- Review recent page additions/removals
- **Metadata validation**: Run `python3 v2/scripts/llms/validate-llms-metadata.py --report` before edits; update Content-Tiefe, Content Types, and header counts if drift
- Check for broken URLs (use validator script; periodic only – slow)
- Review content changes on key pages
- Check sitemap for new pages
- **Duplicate prevention**: Search file for URL before adding; ensure same content is not in multiple sections
- **Outdated content**: Remove or update past event dates (webinars, trade shows >1 year old); update year-dependent keywords (e.g., "ab 2025" → "ab 2026")
- **Tag format**: Blog entries use `[TYPE: YYYY-MM-DD | X Min | N Wörter]` when metadata available; pillar: `[GUIDE: X Min Read | Pillar | Umfassend]`; category: `[CATEGORY: Name | Count | Description]`. See LLM_FILES_GUIDE.md.

### Post-Update Validation

- All URLs return 200 status codes
- Dates are current
- ACAO framework properly implemented
- Semantic richness enhanced
- Section ordering logical
- No duplicate entries
- URLs match sitemap entries
- Descriptions match page content

## Common Patterns

### Product Page Entry

```
> [PRODUCT: Cloud | Mobile Apps | Priority] Product Name - Description (Action) für audience (Context) mit features (Advantage) und measurable results (Outcome)
https://www.ordio.com/product-slug
```

### Guide/Pillar Page Entry

```
> [GUIDE: 15 Min Read | Pillar | Umfassend] Guide Title - Description (Action) context (Context) advantage (Advantage) outcome (Outcome)
https://www.ordio.com/insights/guide-slug/
```

### Tool/Calculator Entry

```
> [CALCULATOR: Instant | Kostenlos | Top] Tool Name - Description (Action) für use case (Context) mit features (Advantage) und benefit (Outcome)
https://www.ordio.com/tools/tool-slug
```

## Validation Scripts

1. **Metadata Validator** (run before commits when editing LLM files): `v2/scripts/llms/validate-llms-metadata.py`
  ```bash
   python3 v2/scripts/llms/validate-llms-metadata.py --report
  ```
   Validates content counts, keywords (year refs), FAQ count, header consistency.
2. **URL Validator** (periodic only – slow; run monthly/quarterly, not every change): `v2/scripts/llms/validate-llms-urls.py`
  ```bash
   python3 v2/scripts/llms/validate-llms-urls.py --file both
  ```
3. **Content Checker**: `v2/scripts/llms/validate-llms-content.py`
  ```bash
   python3 v2/scripts/llms/validate-llms-content.py --file both --sample 10
  ```

## Related Documentation

- `docs/seo-strategy-2026/LLM_FILES_GUIDE.md` - Complete format specification
- `docs/seo-strategy-2026/LLM_FILES_MAINTENANCE.md` - Maintenance procedures
- `docs/content/blog/guides/SEO_BEST_PRACTICES_2026.md` - SEO/GEO/AEO strategies