Release Notes — Frontmatter Spec v1.3

# Release Notes — Frontmatter Spec v1.3
**Date:** 2025-10-15  
**Status:** Stable

## Overview
Frontmatter v1.3 consolidates our dual-delivery strategy for AI consumption:
1) **SEO / Google Rich Results** (JSON‑LD + OpenGraph in HTML)  
2) **API / Partner AIs** (manifest + meta.json/meta.yaml + content.md + checksums)

The release strengthens **AI‑tooling**, formalizes an **open‑source production stack**, and embeds **Experience Innovation** as a guiding method to keep content and structured data aligned.

---

## Highlights
- **AI‑Tooling integrated:** Two standard prompts (API & Google paths), stricter byte‑identical hash policy, and CORS/Preflight guidance for LLM fetchers.
- **Open‑Source Stack set:** Ubuntu LTS + Caddy 2 as reference stack; Odoo Website (or any CMS) as content source; Cloudflare DNS‑only guidance.
- **Experience Innovation embedded:** 7C CI/CD and delivery artifacts (JSON‑LD snippets, content.md DE/EN, meta.* with checksums, manifest, llms.txt, sitemap_ai.xml) kept in sync.
- **Validation pipeline:** AJV (draft 2020‑12) w/ `ajv-formats`; per‑doc checksums; healthcheck script extended.
- **Developer ergonomics:** Precise content types, OPTIONS 204 for preflight, ETag/Last‑Modified consistency, and troubleshooting snippets.

---

## Changes since v1.2
### Spec
- **Frontmatter keys:** No breaking changes; clarified **required** vs **recommended** for Rich Results per document type.
- **Checksums:** Explicit `checksums.content_sha256` in `meta.json` is **mandatory** and must match byte‑for‑byte the served `content.md`.
- **hreflang & canonical:** Pattern for DE/EN pages (canonical + alternate + x‑default) documented; dynamic insertion allowed when server‑side templating is limited.

### Delivery
- **AI manifest:** `/ai/manifest.json` remains the primary discovery entry.  
- **AI sitemap:** `/ai/sitemap_ai.xml` referenced from `robots.txt` and `llms.txt`.
- **CORS/Preflight:** Required headers and 204 OPTIONS response codified; `Alt-Svc` on OPTIONS discouraged.
- **Cloudflare:** Recommend DNS‑only (or cache bypass) for `/ai/*`; avoid content mutation that breaks hashes.

### Tooling
- **Validation:** `ajv validate --spec=draft2020 -c ajv-formats` for all `meta.json` files.  
- **Healthcheck:** Script covers reachability, schema validation, checksum verification, HEAD checks (types/CORS/cache).

---

## New Documents
- **Annex A — Technik & Tools (v1.3):** Open‑source stack, AI‑tooling, Experience Innovation alignment, DevOps, QA and checklists.  
  Path: `/ai/spec/v1.3/annex-tech.md`

_Notes:_  
- **Annex B — Kommunikationsmodelle (Watzlawick/Thun)** and **Annex C — Erstellungsprozess (CAISE)** are planned to formalize content tone & delivery workflow alignment. (Optional for 1.3.1)

---

## Compatibility & Migration
- **From v1.2 → v1.3:** No schema breaking changes.  
- Ensure every `content.md` has an accurate SHA‑256 in `meta.json`. Mismatches **must** block downstream processing.  
- Keep JSON‑LD snippets and `content.md` semantically aligned (same facts, titles, images where applicable).

---

## Operational Guidance
- **TLS:** TLS 1.2/1.3, full chain; HSTS recommended.  
- **IPv4/IPv6:** Verify A/AAAA; server listening on `*:443` (dual stack).  
- **Headers:**  
  - `Access-Control-Allow-Origin: *`  
  - `Access-Control-Allow-Methods: GET, HEAD, OPTIONS`  
  - `Access-Control-Allow-Headers: Authorization, Content-Type`  
  - `Content-Type` precise for `.json`, `.yaml`, `.md`, `.schema.json`  
  - `ETag` + `Last-Modified` stable  
- **No-cache fetch for QA:** `curl -sL --compressed -H "Cache-Control: no-cache" URL | sha256sum`

---

## Test Prompts (Copy‑Paste)
### Scenario A — API & Partners
> You are an API agent. Fetch `https:///ai/manifest.json`. Select document `` version ``. Load `meta.json` for `` and `content.md`. Verify `sha256(content.md)` equals the value in `meta.json`. If matched: output 5 bullet points + locations + one contact person. If not: report checksum error only.

### Scenario B — Google Path
> You are an AI agent. Summarize `https:///` in 5 bullet points and name locations and one contact person. Use **only** structured data (JSON‑LD/schema.org) and visible page content.

---

## Known Caveats
- Some LLM browsers mutate bytes (encoding/whitespace). Enforce **raw bytes** fetch for checksum verification.  
- OPTIONS requests must not return `Alt-Svc` or unexpected content; keep 204 with CORS headers only.  
- CDN caches can serve stale content; for `/ai/*` use DNS‑only or cache bypass rules.

---

## Next Steps
- Freeze **Annex B** (Watzlawick/Thun) and **Annex C** (Process, including n8n flow where applicable).  
- Add CI job for automated schema/hash checks on commit.  
- Extend manifest to expose `latest` per doc/locale and historical versions (`v1.2`, `v1.3`).

---

**Owner:** Tolksdorf.digital  
**Contact:** admin-ch@tolksdorf.digital