Live demo

One JSON file becomes this

Everything below, navigation, search, theme, code, diagrams, charts, math, citations, and an interactive review board, lives in one self-contained HTML file with no external assets. The page is a projection of the JSON your AI wrote ^[1].

43 block typesSelf-containedAgent-readableLight + dark

Sourceone .dossier.json

Outputone .html

Runtime deps0

Use the full-page toolbar. In the full HTML artifact, Edit changes text in place, the color swatch restyles live in the Theme Studio, and Export gives you Markdown, JSON, or the agent digest. From the CLI, dossier export also writes Word (charts and diagrams embedded as images) or PDF.

43Block types+1 citation block

0Runtime depsview-time network free

2Renderers (Node + React)same model

100%Self-containedHTML + source

For humans

A navigable, searchable, themeable page, not a wall of Markdown.

For agents

The full model is embedded as #dossier-model; read one block, no scraping.

For your wiki

One portable file, link it, email it, or <iframe> it anywhere.

Structure & prose

Sections nest other blocks; text fields take inline markdown.

This is a prose block with inline code, a link, and a footnote.¹

Bullet lists render as real lists.
Inline markdown still works inside list items.

Numbered lists work too.
Paragraph rhythm stays intact.

A second paragraph to show vertical rhythm.

How it's built

AuthorAn agent writes a *.dossier.json.

Validatedossier build validates and lints.

RenderJSON becomes HTML + the data island + Markdown.

UseRead, decide, export, embed.

Roadmap

0.1done

Generator, catalog, features.

0.2done

MCP, plugins, new blocks.

0.5done

Process workflows, publishing, embed output, and live editor hooks.

Composable. Sections, two-col, and tabs nest other blocks.

Self-contained. No external fonts, scripts, or images. Works offline.

Reference blocks

render.ts

import { renderDossier } from "@kylebegeman/dossier-react";
const { html, md } = await renderDossier(model); // one self-contained file

bash

dossier init my-doc
dossier build my-doc.dossier.json && open my-doc.html

Pipeline

The loop (Mermaid)

Exports

Format	Use
HTML	The page humans open
Markdown	Plain-text copy
JSON / digest	What agents read

Source	Signal	Use
Repository	Source + docs	Clone, star, contribute

FAQ

Does it replace my docs site?

No, it's a companion: linkable, embeddable, exportable artifacts.

Media & data

Adoption (bar)

Trend (area)

E = mc^2 \quad\text{and}\quad \int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}

Images are inlined as data URIs at build time.

Decisions & trust

Where it lives

Option	Cross-project	Public later
Standalone repo recommended	Yes	One-line flip
Inside a monorepo	No	Hard

Risks

Risk	Likelihood	Impact	Mitigation
Scope creep	medium	medium	Freeze the schema, then build.

Try it

Install: npm i -g github:kylebegeman/dossiertodo
Run: dossier init demo && dossier build demo.dossier.jsontodo

Assumptions & open questions

assumptionOne file beats a folder of assets for sharing.verified

Interactive review board, try it

Selected only0 selected

ITEM-002

Themeable

Light + dark, per-project token overrides, fully responsive to mobile.

DesignImpact · HighEffort · -

shipped

The whole design is a small token system; one accent, near-monochrome neutrals.

Notes

Process board, implementation loop

With verdict only0 verdicts

ITEM-001

Extract a work item

Use verdicts and notes to steer actual implementation work.

ImplementationPriority · P1Owner · agentImpact · MediumEffort · Small

proposedVerdict

Pick a verdict, leave notes, then export process JSON. An agent reads that packet with dossier_read_process and acts on the accepted work.

preview.diff

diff --git a/src/generate.mjs b/src/generate.mjs
@@ -1 +1 @@
-// plan-only surface
+// process-aware surface

Files: src/generate.mjs, src/runtime/runtime.mjs
Verification: npm test
Packet: dossier.process/v1
Verdicts: approve, revise, skip, defer, split, retry, block

Notes

Patch set, proposed edits

Implementation dossiers can carry proposed patches grouped by intent, files, work items, risk, and verification.

Patch process-aware surface

Move the artifact from a plan-only surface to a process-aware one.

modifyproposedRisk · low

Patch verdictReview notes

Files: src/generate.mjs
Work items: extract-work-item
Verification: npm test

Diff

1 file+1-1

src/generate.mjs+1 -1

File verdictFile comment

diff --git a/src/generate.mjs b/src/generate.mjs--- a/src/generate.mjs+++ b/src/generate.mjs

@@ -1,2 +1,2 @@Hunk verdict

1-// plan-only surface1+// process-aware surface

Code editor, editable snippet

Small edits can round-trip as dossier.edits/v1 without turning the artifact into a full IDE.

runtime.mjs

jssrc/runtime/runtime.mjsWork · extract-work-item

function exportEdits(state) {
  return { schema: "dossier.edits/v1", edits: state.editors || {} };
}

clean

Diff view, file-first review

A standalone unified diff renders with file summaries, hunks, additions, and deletions.

1 file+1-0

src/runtime/runtime.mjs+1 -0

File verdictFile comment

diff --git a/src/runtime/runtime.mjs b/src/runtime/runtime.mjs--- a/src/runtime/runtime.mjs+++ b/src/runtime/runtime.mjs

@@ -1,3 +1,4 @@Hunk verdict

11 const state = loadState();2+state.process = state.process || {};23 34 exportProcess(state);

Process closeout blocks

The same artifact now covers implementation, review, integration, release, and incident loops.

Verification run

Test suite

status · passedkind · passed

command: npm test
expected: All tests pass.
actual: 17 passing.

Evidence log

Build log

npm test completed successfully.

kind · commandtrust · high

source: local

Trust report

A provenance layer ties claims to source ids and verification evidence for agent readback.

Sources

Source	Kind	Trust	License	Summary
npm test	command	high		Local test command recorded in the verification run.
Public manual QA guide	doc	medium		Manual browser, live serve, MCP, export, and release gate checklist.

Automated tests pass for the process block family.

status · verifiedconfidence · high

notes: Agents can read this with dossier_read_trust.

npm testtest-suite

The feature set is ready for public manual QA.

status · partialconfidence · medium

notes: Manual QA still needs a human browser pass before broad announcement.

Public manual QA guidebuild-log

Apply gate

Approve, revise, skip, defer, split, retry, or block this process packet.

VerdictNotes

Review findings

Missing evidence link

Attach the verification run to the work item before closeout.

severity · medium

recommendation: Link the finding to a verification-run id.
files: src/starters/review.dossier.json

Review thread

Agent access

Kyle
Make the packet readable without DOM scraping.
Agent
Use MCP readback and versioned export packets.

Integration cycles

Producer to consumer

Consumer project accepted the packet shape.

status · done

Integration report

producer: dossier
consumer: lumen
status: accepted
version: 0.5.5
next step: Dogfood against a live dependency change.

Process packets

Verdicts, releases, edits, and process state all export as structured packets.

Upstream response

upstream: CodeMirror host adapter
status: accepted
request: Enhance data-code-editor hooks in the local serve runtime.
response: dossier serve now loads CodeMirror 6 locally and keeps textarea-backed packet export/save-back intact.
next step: Keep Monaco reserved for hosted Studio or Lumen integrations.

Release checklist

Tests passrequiredpassednpm test
Docs regeneratedrequiredpassedREADME and public manual QA guide refreshed.

Decision log

host-runtime

Dossier records state and evidence while CLI, MCP, Lumen, or another host performs filesystem and Git work.

owner · Kyle + Codex

decision: Keep execution in host tools

Glossary

island: The embedded #dossier-model JSON that is the source of truth for the page.

Notes

Reference a note inline with a bracketed caret id; it links here and back. ↩

Citations

Dossier README
Kyle Begeman · 2026 · GitHub · accessed 2026-07-03
Canonical feature and workflow overview for the Dossier project.

One JSON file becomes this

For humans

For agents

For your wiki

Structure & prose

How it's built

Roadmap

Reference blocks

Pipeline

The loop (Mermaid)

Exports

FAQ

Media & data

Adoption (bar)

Trend (area)

Decisions & trust

Where it lives

Risks

Try it

Assumptions & open questions

Interactive review board, try it

Navigation

Themeable

Process board, implementation loop

Extract a work item

Patch set, proposed edits

Patch process-aware surface

Diff

Code editor, editable snippet

Diff view, file-first review

Process closeout blocks

Verification run

Test suite

Evidence log

Build log

Trust report

Sources

Automated tests pass for the process block family.

The feature set is ready for public manual QA.

Apply gate

Review findings

Missing evidence link

Review thread

Agent access

Integration cycles

Producer to consumer

Integration report

Process packets

Upstream response

Release checklist

Decision log

host-runtime

Glossary

Notes

Citations