# lagom.md

> A markdown-first, machine-structured document format for building knowledge bases that can be read by people, rendered by software, and understood by AI agents.

lagom.md defines interactive documents (`.idoc.md` / `.idoc.json`) — a structured, reactive document primitive built on top of the Chartifact schema. Documents contain markdown content, interactive elements (sliders, dropdowns, charts, tables), reactive variables, and data loaders — all sandboxed with no custom script execution.

## Site structure

- [Homepage](https://lagom.md/): Overview and introduction
- [Documentation Index](https://lagom.md/docs/): All documentation pages
- [Document Specification](https://lagom.md/docs/spec): Full schema reference — element types, variables, data loaders, governance metadata
- [Processor Pipeline](https://lagom.md/docs/processor): The 7-step pipeline: parse, validate, normalize, enrich, render, govern, assist
- [Examples](https://lagom.md/docs/examples): Complete document examples — SOPs, policies, playbooks, decisions, agent-ready workflows
- [Demos](https://lagom.md/docs/demos): Interactive side-by-side demos showing source and rendered output
- [Changelog](https://lagom.md/docs/changelog): Monthly changelog for the spec
- [JSON Schema](https://lagom.md/schema/v1/idoc_v1.json): Machine-readable schema for `.idoc.json` validation
- [TypeScript Types](https://lagom.md/schema/v1/idoc_v1.d.ts): TypeScript type definitions
- [Full LLM reference](https://lagom.md/llms-full.txt): Complete spec in plain text for AI agent consumption

## File formats

- `.idoc.md` — Markdown interactive document (preferred for human authoring)
- `.idoc.json` — JSON interactive document (for programmatic generation)

## Core concepts

- **Elements**: chart, checkbox, dropdown, image, mermaid, number, presets, slider, tabulator, textbox, treebark
- **Variables**: Reactive shared state layer with types: number, string, boolean, object
- **Data loaders**: inline, file, or URL-based data sources (JSON, CSV, TSV, DSV)
- **Groups**: Ordered sections; first group should have `groupId: "main"`
- **Security**: Sandboxed rendering, no custom JavaScript execution in documents

## For AI agents

To generate a valid Lagom document:
1. Use `.idoc.md` format with YAML-configured element blocks
2. Follow snake_case variable naming (no digits at start, no spaces/operators)
3. Include governance metadata: Owner, Review cadence, Last reviewed, Status
4. Validate against the JSON schema at https://lagom.md/schema/v1/idoc_v1.json

For full spec details, read: https://lagom.md/llms-full.txt