# K9 Pandoc Reader, Writer, and Filter

## Summary

Custom Pandoc reader, writer, and Lua filter for K9 Self-Validating Components — a security-tiered service configuration format built on Nickel, with three trust levels (Kennel, Yard, Hunt) and structured pedigree metadata.

K9 files come in two syntaxes: YAML (`.k9`) for Kennel-level configs and Nickel (`.k9.ncl`) for Yard/Hunt-level components with contracts, recipes, and cryptographic signing. This tooling enables converting K9 documents to HTML, PDF, DOCX, Markdown, and all other Pandoc-supported formats.

## Components

- **k9.lua** — Comprehensive Pandoc custom reader (597 lines). Auto-detects YAML vs Nickel syntax, extracts pedigree metadata, identifies security trust level, and parses records, contracts, recipes, and bindings into the Pandoc AST.
- **k9-reader.lua** — Lightweight reader variant (92 lines) for quick extraction.
- **k9-writer.lua** — Custom Pandoc writer (230 lines). Converts any Pandoc AST to valid K9 Nickel output with pedigree blocks, security settings, recipe definitions, and proper multiline string syntax (`m%"..."%`).
- **k9-filter.lua** — Post-processing Lua filter with four passes: security badge colouring (green/amber/red for trust levels), contract annotation highlighting, recipe command validation (80+ known tools), and pedigree completeness checking.
- **k9.html** — HTML5 Pandoc template with security-level-adaptive header bar, pedigree summary card, contract styling, recipe blocks with labels, copy-to-clipboard on code blocks, and responsive/print-friendly layout.

## Usage

```sh
# K9 Nickel to HTML (full pipeline)
pandoc -f k9.lua input.k9.ncl \
  --lua-filter=k9-filter.lua \
  --template=k9.html \
  -o output.html

# K9 YAML to PDF
pandoc -f k9.lua config.k9 -o output.pdf

# Round-trip: K9 to AST to K9
pandoc -f k9.lua input.k9.ncl -t k9-writer.lua -o roundtrip.k9.ncl
```

## Requirements

- Pandoc 3.0+ with Lua support

## Spec

- K9 SVC specification: <https://github.com/hyperpolymath/standards/tree/main/k9-svc>
- Media type: `application/vnd.k9+nickel` (IANA registration pending)

## Related

- [pandoc/lua-filters](https://github.com/pandoc/lua-filters) — Community Lua filters repository
- [K9 LSP server](../lsp/) — Language Server Protocol implementation
- [VS Code extension](../editors/vscode/) — Syntax highlighting for VS Code
- [K9 specification](../SPEC.adoc) — Full K9 SVC specification
- [Pedigree contract](../pedigree.ncl) — Nickel contract defining component structure

## License

PMPL-1.0-or-later (Palimpsest License)

## Author

Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
