> A living document is one that records not just what it says, but how it came

A living document is one that records not just what it says, but how it came to say it. The default template routes headings to content, quotes to commentary, tables to data, and links to reference. phlee treats humans and AI as peers in the contribution graph, so every edit is tracked, layered, and reversible. The goal: an AI collaboration trail that is as portable and auditable as the document itself — no chat-session lock-in, no lost context, no un-reviewable edits.

phlee — a living document standard

phlee is a single-file document format that is both source and container. One file is the substrate: it holds the content, the layer structure, the section outline, and the collaboration history — all in one place, edited as a single unit.

Why a living document

Traditional documents separate the source from the container. A .docx is a container but not a source; a .md is a source but not a container. phlee collapses this: the file you edit is the file you publish, and it carries its own structure and history with it.

The result is a document that is:

• Self-contained — everything lives in one file.
• Transparent — the layer structure is visible, not hidden.
• Accountable — every change is attributable to a contributor.
• Forward-compatible — unknown extensions degrade gracefully.

Core principles

• One file = the substrate. A .phlee file is complete and standalone.
• Unified canvas editing. The whole document is edited as one unit; layers are an overlay, not separate documents.
• Forward-compatible. Unknown layer kinds and compositing strategies degrade gracefully rather than failing to load.
• Versioned. The binary header carries the format version; the manifest carries an informational display string.

Physical layout

A .phlee file is three regions:

The header is fixed-size and little-endian. The manifest is JSON. The layer data is a contiguous block of per-layer bytes, framed by offsets in the manifest.

Header fields

Layers

A layer is a named, typed stream of bytes. Layers are the core of phlee's "visual writing" model: each layer has a kind, a color, and a compositing strategy.

Layers are composited into a unified view: the document reads as one continuous flow, with each span retaining its layer identity and color.

Compositing strategies

• layered_z_index — layers stack by z-order.
• flow_based — layers flow inline.
• grid_based — layers align to a grid.

Unknown strategies fall back to a renderer default.

Sections

Sections are the document's outline. They are derived live from two sources:

• Markdown headings — # Heading, ## Sub, etc. become sections automatically.
• Explicit markers — a marker of the form { # id @ layer ! tag1,tag2 } for precise control. (Written here without the braces so it is not parsed as a real marker.)

Sections nest by depth and drive the table-of-contents HUD: an expandable, searchable, layer-coded navigation panel.

Import and conversion

phlee can convert existing documents (Markdown, HTML, plain text) into a layered .phlee file. Formatting is preserved as much as possible, and content is split into layers using layer identification templates — user-defined rules for how content should be layered.

Import house-styles each layer losslessly and idempotently (a single # title, heading spacing, > [!kind] callouts, pipe-table separators), so the stored bytes are the published content and re-importing is a stable no-op. Each layer also carries a tier — the semantic document kind (framework / vehicle / thesis / policy / general) — distinct from its syntactic kind; the document sets a default tier and layers may override it.

The default template

Multi-user collaboration

phlee is designed as a contribution-tracking standard. The main document is created first, then users are assigned a profile layer — either a direct layer in the main doc, or a layer on a separate profile doc. All of a user's contributions are tracked within their own layer, and can be merged into the main document later based on voting.

Concepts

• User — a participant identified by id and name.
• ProfileLayer — a per-user container holding contributions, annotations, and stats.
• Contribution — a proposed edit to a section, tracked in the author's layer until accepted.
• Annotation — a note attached to a section, recorded on the annotator's layer.
• UserStats — per-user counters: contributions, accepted, rejected, annotations.

Contribution lifecycle

1. A user authors a contribution targeting a section. It is stored in their profile layer with status pending, along with its rationale and a fingerprint of the section as it was when proposed.
2. Other users vote on it (approve / reject). Votes are idempotent and an author cannot vote on their own contribution.
3. An acceptance policy evaluates the votes: accepted when it has enough votes and a sufficient approval ratio.
4. Accepted contributions are merged into the main document only if the target section still matches the author-time fingerprint; the marker is never overwritten. Stale proposals are marked conflicted for triage rather than silently overwriting newer work — merging behaves like a version-control system.

Tracking AI edits

The same profile-layer model tracks AI edits and contributions. An AI assistant is just another user with a profile layer: its edits are isolated, reviewable, and mergeable on the same terms as any human contributor. This gives full provenance — every change to the document is attributable to a contributor, human or machine.

AI potential pathways

phlee is designed not just to store AI-assisted work but to make it auditable, reviewable, and collaborative. The following pathways are the intended evolution:

• Provenance-aware generation — an agent edits within its own profile layer; every change carries model, a prompt_hash linking to the full prompt stored elsewhere, and a response_excerpt so the reasoning is visible without bloating the file.
• Conversation-as-provenance — the full discussion thread (arguments) attached to a contribution is preserved and queryable, so a decision retains the why, not just the what.
• Review-and-merge, not overwrite — AI contributions follow the same fingerprint-guarded merge as human ones: they cannot silently clobber newer work, and stale proposals surface as conflicts for triage.
• Semantic diff at the layer level — because sections and layers are explicit, diffs between AI revisions are meaningful (editorial intent), not noisy text hunks.
• Audit export — a complete provenance trail (phlee provenance audit) produces JSON/Markdown for compliance, reproducibility, and team reviews.

The editor

The phlee editor is a unified text surface with:

• live color-coded highlighting of headings, markers, and layer spans
• a live table of contents that rebuilds as you type
• a layer dropdown to assign text to layers
• a live preview pane
• a utility panel with ToC, Layers, Preview, and Stats tabs
• native file dialogs for open, save, save-as, and import

CLI

The phlee CLI provides the full toolset:

phlee pack <manifest.json> <layer:file>... [-o out.phlee]
phlee unpack <file.ph> <dir>
phlee inspect <file.ph>
phlee validate <file.ph>
phlee extract-layer <file.ph> <layer-id>
phlee scan <file.ph>
phlee diff <a.phlee> <b.phlee>
phlee render <file.ph> [-o out] [--format html|markdown] [--toc hud|none] [--provenance]
phlee export <file.ph> [--format html|md|pdf] [--state none|provenance|full] [-o out]
phlee export --extract <artifact> [-o recovered.phlee]
phlee import <file> [-o out.phlee] [--format auto|markdown|html|plain]
phlee template list
phlee profile <add-user|add-contribution|argue|vote|merge|list|detail> ...
phlee provenance <trace|audit|list|conversation> ...
phlee git <clone|status|pull|commit|push|merge3> ...

Exports & embedded state

A .phlee document exports to HTML, Markdown, or PDF, each carrying an embedded, compressed snapshot of the document state. Every export includes at least a baseline provenance line — the format version and when the file was separated — so no artifact is ever bare. Three state levels:

• HTML / Markdown — the state blob is embedded inline (HTML script block / Markdown comment); --extract recovers a full snapshot back into a .phlee.
• PDF — rendered via the typst engine; the state is carried as a companion .state.txt (and can be embedded in PDF metadata).

phlee export doc.phlee --format html --state full -o doc.html
phlee export doc.phlee --format pdf --state full -o doc.pdf   # needs typst
phlee export --extract doc.html -o recovered.phlee            # recover the .phlee

Git & Codeberg

.phlee files live in Git. A diff-friendly Markdown mirror (doc.md) is committed alongside the authoritative binary (doc.phlee) so Codeberg shows readable diffs. Autosave (in-memory), manual Save (disk), and Push (git) are separate actions. After a conflicted pull, a 3-way merge reconciles base / local / remote per-layer at the text level, auto-merging disjoint changes and reporting (never silently resolving) overlaps.

Project specifics

This document is itself a .phlee file. It demonstrates the format by being the format: the source you are reading is the container, layered, sectioned, and ready to track contributions.

• Format version: 1
• Default layers: content, data, commentary, reference
• Default template: default
• Editor: Tauri desktop app (phlee-app)
• CLI: phlee

Roadmap

• custom template authoring editor (done)
• paste-to-import (done)
• live preview (done)
• provenance / audit tooling (done)
• git & Codeberg sync (done)
• exports with embedded state (HTML/MD/PDF) (done)
• PDF export via typst (done)
• per-layer editing controls in the editor
• profile-layer UI in the editor
• AI agent editing pathway (agent profile layer + prompt-hash provenance)
• conversation replay UI
• embed state into PDF metadata (beyond the companion file)
• self-contained PDF via typst-as-a-library (no external binary)

| region | purpose |

region	purpose
Header (32 bytes)	magic, version, offsets
---	---
Manifest (JSON)	title, layers, sections, collaboration
---	---
Layer data	the raw bytes of each layer
---	---
offset	size
--------	------
0	4
---	---
4	1
---	---
5	4
---	---
9	2
---	---
11	2
---	---
13	4
---	---
17	4
---	---
21	4
---	---
25	4
---	---
29	3
---	---
kind	color
------	-------
content	#4a90d9
---	---
data	#27ae60
---	---
commentary	#f39c12
---	---
reference	#9b59b6
---	---
custom	#7f8c8d
---	---
layer	pattern
-------	---------
content	^#{1,6}\s+
---	---
commentary	^\s*>\s+
---	---
data	^\s*|.*|\s*$
---	---
reference	\[[^\]]+\]\([^)]+\)
---	---
level	baseline
---	---
-------	:--------:
---	---
none	✅
---	---
provenance	✅
---	---
full	✅
---	---