# lagom.md — Full Reference for AI Agents

> If you are an AI agent: This is the complete reference for the lagom.md document specification.
> Read this file in full before attempting to generate, parse, or interact with Lagom documents.

---

# Lagom Document Spec (Chartifact Adaptation)

Lagom uses an adapted Chartifact document model to power interactive, AI-readable knowledge assets.

This page is the canonical format reference for how documents are authored in Lagom.

## Why this exists

Chartifact provides the upstream interactive document schema and runtime.
Lagom adopts that foundation, then defines a markdown-first authoring standard suitable for an operational knowledge base in the AI era.

## Upstream source of truth

Chartifact repository:
- https://github.com/microsoft/chartifact

Primary upstream schema references:
- https://microsoft.github.io/chartifact/schema/idoc_v1.json
- https://github.com/microsoft/chartifact/blob/main/docs/schema/idoc_v1.d.ts

Lagom-hosted schema (canonical for Lagom documents):
- https://lagom.md/schema/v1/idoc_v1.json
- https://lagom.md/schema/v1/idoc_v1.d.ts

## What Lagom standardizes

Lagom standardizes the following on top of Chartifact:

1. Markdown-first authoring (`.idoc.md`) as default.
2. JSON authoring (`.idoc.json`) for generated or schema-driven workflows.
3. Variable naming discipline for stable AI and rendering behavior.
4. Predictable document sections for reusable operational knowledge.
5. Safe rendering model (no custom script execution in documents).

## Supported file formats

### 1) Markdown interactive document (preferred)

File suffix:
- `.idoc.md`

Use when:
- Humans are writing/editing content.
- You want clean git diffs and review.
- You want direct rendering with embedded plugin blocks.

### 2) JSON interactive document

File suffix:
- `.idoc.json`

Use when:
- Documents are generated programmatically.
- You need explicit structure-level validation.
- You are building template generators.

Both formats represent the same underlying interactive model.

## Core document model (shared by markdown and JSON)

A Lagom interactive document is conceptually:

- `title`: page title.
- `groups`: ordered sections; first `groupId` should be `main`.
- `variables` (optional): reactive values.
- `dataLoaders` (optional): inline/file/url data sources.
- `resources.charts` (optional): Vega/Vega-Lite specs referenced by chart elements.
- `style` (optional): CSS and optional Google font mapping.
- `notes` (optional): author comments.

## Element types in scope

Lagom follows upstream Chartifact interactive element types:

- `chart`
- `checkbox`
- `dropdown`
- `image`
- `mermaid`
- `number`
- `presets`
- `slider`
- `tabulator`
- `textbox`
- `treebark`

Markdown text is also a first-class page element and supports variable placeholders like `{{variableId}}`.

## Variables and reactivity

Variables are the shared state layer.

Each variable defines:
- `variableId`
- `type`: `number | string | boolean | object`
- `initialValue`
- optional `calculation`

Lagom variable rules:
- Use lowercase snake_case IDs.
- Do not start IDs with digits.
- Do not include spaces or operator characters.
- Do not suffix IDs with the type (example: avoid `score_number`).
- Keep IDs semantically stable to preserve prompt and template compatibility.

## Data sources

Lagom supports upstream data loader patterns:

- `inline` (embedded JSON/CSV/TSV/DSV)
- `file` (uploaded file content)
- `url` (templated URL allowed)

Formats:
- `json`
- `csv`
- `tsv`
- `dsv`

## Security model

Lagom inherits Chartifact safety principles:

- Sandboxed rendering boundaries.
- No custom JavaScript execution in document content.
- Defensive handling of markdown and CSS.

Operational implication:
- If logic requires executable code, move that logic to trusted application services, not document content.

## Lagom authoring conventions

Use this structure for operational documents:

1. `# Title`
2. One short context paragraph (what and for whom).
3. `## Inputs` (interactive controls if needed).
4. `## Current state` (tables/charts/derived values).
5. `## Decisions or actions` (clear next-step section).
6. `## Owner and review cadence` (maintenance metadata).

Recommended metadata block (top of doc body):

```markdown
Owner: @team-or-person
Review cadence: monthly | quarterly
Last reviewed: YYYY-MM-DD
Status: draft | active | deprecated
```

## Minimal markdown example (`.idoc.md`)

````markdown
```json vega
{
  "$schema": "https://vega.github.io/schema/vega/v6.json",
  "signals": [{ "name": "ticket_count", "value": 12 }]
}
```

# Support load overview

Owner: @operations
Review cadence: monthly
Last reviewed: 2026-05-03
Status: active

Current ticket count: **{{ticket_count}}**

```yaml slider
variableId: ticket_count
label: Ticket count
min: 0
max: 100
step: 1
```
````

## Minimal JSON example (`.idoc.json`)

```json
{
  "$schema": "https://lagom.md/schema/v1/idoc_v1.json",
  "title": "Support load overview",
  "variables": [
    {
      "variableId": "ticket_count",
      "type": "number",
      "initialValue": 12
    }
  ],
  "groups": [
    {
      "groupId": "main",
      "elements": [
        "# Support load overview",
        "Current ticket count: **{{ticket_count}}**",
        {
          "type": "slider",
          "variableId": "ticket_count",
          "label": "Ticket count",
          "min": 0,
          "max": 100,
          "step": 1
        }
      ]
    }
  ]
}
```

## Lagom compatibility notes

- Existing Lagom projects use markdown and JSON interactive docs in parallel.
- Build pipelines may stage Chartifact runtime subprocessors into public assets for browser rendering.
- For website/app consistency, keep shared templates format-stable and avoid plugin-specific drift unless intentionally versioned.

## Recommended governance

1. Treat this file as the living spec and update via pull request.
2. Require schema validation for `.idoc.json` files in CI.
3. Add a lint pass for variable naming and required metadata in `.idoc.md` files.
4. Version any breaking format changes (for example: `lagom-doc-spec-v2`).

## Change log

- 2026-05-03: Initial Lagom adaptation spec based on Chartifact `idoc_v1` model.

---

## Processor pipeline

The Lagom processor handles documents through 7 steps:

1. **Parse** — Read `.idoc.md` or `.idoc.json` into the internal document model
2. **Validate** — Check against JSON Schema and Lagom naming conventions
3. **Normalize** — Resolve defaults, expand shorthand, ensure group structure
4. **Enrich** — Compute derived variables, resolve data loaders
5. **Render** — Generate interactive HTML with reactive bindings
6. **Govern** — Enforce metadata requirements, review cadence, ownership
7. **Assist** — Provide AI-agent-readable summaries and action suggestions

---

## Governance and metadata

Every production Lagom document should include:

- `Owner`: team or person responsible
- `Review cadence`: how often it should be reviewed (monthly, quarterly)
- `Last reviewed`: ISO date of last review
- `Status`: draft | active | deprecated

This metadata enables automated governance workflows and AI agent understanding of document freshness and authority.

---

## How AI agents should interact with Lagom documents

### Reading documents
- Parse the `.idoc.md` or `.idoc.json` format
- Extract variables and their current values
- Understand the document structure via groups and elements
- Check governance metadata for freshness

### Generating documents
1. Use `.idoc.md` format (preferred for readability)
2. Follow the authoring conventions structure
3. Use snake_case for all variable IDs
4. Include governance metadata block
5. Validate against: https://lagom.md/schema/v1/idoc_v1.json

### Modifying documents
- Preserve existing variable IDs (they may be referenced externally)
- Update `Last reviewed` date when making changes
- Keep the document structure conventions intact

---

## Site map

- https://lagom.md/ — Homepage and introduction
- https://lagom.md/docs/ — Documentation index
- https://lagom.md/docs/spec — Full specification reference
- https://lagom.md/docs/processor — Processor pipeline details
- https://lagom.md/docs/examples — Complete document examples
- https://lagom.md/docs/demos — Interactive demos
- https://lagom.md/docs/changelog — Changelog
- https://lagom.md/schema/v1/idoc_v1.json — JSON Schema
- https://lagom.md/schema/v1/idoc_v1.d.ts — TypeScript types
- https://lagom.md/llms.txt — Summary index
- https://lagom.md/llms-full.txt — Full reference (this file)

---

## Links

- GitHub: https://github.com/withlagom
- Contact: success@withlagom.com
- Schema: https://lagom.md/schema/v1/idoc_v1.json
- TypeScript types: https://lagom.md/schema/v1/idoc_v1.d.ts