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 serialization Human-authored. YAML frontmatter + typed fenced blocks. Optimized for reading, writing, git diffs, and AI agent comprehension.
• .lagom.json — JSON serialization Machine-canonical. Strict schema structure. Optimized for programmatic access, validation, rendering engines, and automation pipelines.
• Lossless round-trip Both 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, giving Lagom documents a consistent internal shape while allowing them to be authored naturally in Markdown.

interface LagomDocument {
  $schema: string;
  lagomVersion: string;
  kind: "LagomDocument";
  id: string;
  title: string;
  description?: string;
  documentType:
    | "sop"
    | "policy"
    | "playbook"
    | "decision"
    | "guide"
    | "workflow";
  status: "draft" | "active"
    | "deprecated" | "archived";
  owner?: OwnerRef;
  sections: LagomSection[];
  variables?: LagomVariable[];
  entities?: BusinessEntityRef[];
  connectors?: ConnectorRef[];
  actions?: AgentAction[];
  governance?: GovernanceMetadata;
}

interface LagomSection {
  id: string;
  title: string;
  elements: LagomElement[];
}

type LagomElement =
  | MarkdownBlock
  | StepBlock
  | ChecklistBlock
  | DecisionBlock
  | PolicyRuleBlock
  | PromptBlock
  | AgentActionBlock
  | DataReferenceBlock
  | ApprovalBlock
  | SystemReferenceBlock
  | MermaidBlock
  | TableBlock;

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

Trapped in documents that go stale, systems that do not talk to each other, and processes that only live in someone's head. Lagom turns knowledge into a durable operational layer.

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