A New Kind Of Document, built for Humans & Agents

Why we forked Chartifact

We forked Microsoft's Chartifact because it proved an important idea: documents do not have to be static blobs. They can be portable, declarative artifacts that combine Markdown, structured JSON, data references, variables, and renderable components. Lagom extends that idea from interactive analytics documents into operational knowledge documents for SOPs, policies, playbooks, workflows, prompts, decisions, and agent-ready business context.

One document, two serializations

Every Lagom document is a single typed knowledge artifact that can be serialized in two interchangeable formats. The filename convention name.lagom.md or name.lagom.json identifies a topic in the Lagom document format — the suffix determines the serialization, not the content.

• .lagom.md — Markdown serializationHuman-authored. YAML frontmatter + typed fenced blocks. Optimized for reading, writing, git diffs, and AI agent comprehension.
• .lagom.json — JSON serializationMachine-canonical. Strict schema structure. Optimized for programmatic access, validation, rendering engines, and automation pipelines.
• Lossless round-tripBoth serializations compile to the identical LagomDocument object tree. Convert freely between formats without data loss — they are equivalent representations of the same artifact.

---
type: sop
owner: customer-success
status: active
reviewCadence: quarterly
systems:
  - HubSpot
  - Google Drive
---

# Client Onboarding

```lagom.step
id: create-client-folder
title: Create client folder
tool: google_drive.create_folder
```

{
  "type": "sop",
  "owner": "customer-success",
  "status": "active",
  "reviewCadence": "quarterly",
  "systems": ["HubSpot", "Google Drive"],
  "title": "Client Onboarding",
  "elements": [
    {
      "elementType": "step",
      "id": "create-client-folder",
      "title": "Create client folder",
      "tool": "google_drive.create_folder"
    }
  ]
}

Reads like a wiki page.
Works like a process engine.

A Lagom document renders just like a wiki page — anyone on the team can read it, understand the process, and follow along. But beneath the surface, every step, tool binding, and approval gate is structured so that an agent can parse the document, understand the workflow, and execute it autonomously.

The left panel is what every knowledge base gives you — prose that a human can read but a machine cannot act on. The right panel is the same process as a Lagom document: still human-readable, but now with typed steps, explicit tool bindings, ownership, and agent actions that turn documentation into automation.

# Client Onboarding

When a client signs, create a folder,
schedule kickoff, and send the
welcome packet.

← no structure for agents to parse
← no defined steps or owners
← no tool bindings or approval rules
← no way to automate

── metadata: who owns this, what systems are involved ──
type: sop
owner: customer-success
status: active
reviewCadence: quarterly
systems:
  - HubSpot
  - Google Drive
  - Slack

── step: agent knows what to do and which tool to call ──
step:
  id: create-client-folder
  title: Create client folder
  owner: account-manager
  tool: google_drive.create_folder
  requiresApproval: false

── agent_action: autonomous execution with approval gate ──
agent_action:
  id: send-welcome-packet
  tool: gmail.send_email
  requiresApproval: true

The LagomDocument object

At the center of Lagom is the LagomDocument. Each document is composed of sections and typed elements organized into 6 categories, giving Lagom documents a consistent internal shape while allowing them to be authored naturally in Markdown.

interface LagomDocument {
  $schema?: string;
  title: string;
  description?: string;
  icon?: DocumentIcon;
  cover?: DocumentCover;
  documentType?: string;
  tags?: string[];
  status?: "draft" | "active"
    | "deprecated" | "archived";
  owner?: string;
  reviewCadence?: string;
  systems?: string[];
  triggers?: Trigger[];
  variables: Variable[];
  groups: Group[];
  dag?: ProcessDAG;
  governance?: GovernanceMetadata;
}

interface ProcessDAG {
  nodes: DAGNode[];
  edges: DAGEdge[];
}

interface DAGNode {
  id: string;
  elementType: ProcessElementType;
  label?: string;
  retry?: RetryPolicy;
  timeout?: string;
  approval?: ApprovalConfig;
}

interface DAGEdge {
  from: string;
  to: string;
  condition?: string;
  type: "sequential" | "conditional"
    | "parallel" | "join";
}

interface DocumentIcon {
  type: "emoji" | "icon";
  value: string;
  iconSet?: string;
  color?: string;
}

interface DocumentCover {
  src: string;
  alt?: string;
  position?: number;
}

Element categories

All element types are organized into 6 categories. Each category serves a distinct role in the document system.

The ProcessDAG

Documents with process elements automatically derive a DAG — a directed acyclic graph. A DAG is a structure where tasks flow in one direction without cycles, making it possible to model execution order, parallelism, and conditional branching in a way that agents and orchestrators can follow without re-parsing prose.

The ProcessDAG is serialized as document-level metadata. Process elements declare retry policies, timeouts, approval gates, triggers, and parallel flows. See the Flows & Process Engine reference for the full specification.

Human-readable by design

Lagom documents are designed to remain useful even without the Lagom application.

This makes Lagom documents easy to review in GitHub, edit in a text editor, generate with AI, inspect during audits, and migrate over time.

Built for AI agents

AI agents need more than prose. They need context, constraints, tools, and structure. Lagom documents can describe:

That makes each document both a human guide and an agent-readable instruction layer.

Company knowledge is usually trapped. Not anymore.

Stale documents, disconnected systems, processes that only live in someone's head. Lagom gives knowledge a shape that humans can read, software can validate, and AI agents can act on.

That is the foundation for an AI-native knowledge base. Not a wiki with a chatbot bolted on. A living company brain built on a document spec that both people and machines can trust.