Behavior and specifications

This section describes how liel behaves today: feature coverage, reliability, and the byte-level file format. For the rationale behind the scope, see Design.

CLI documentation map

Use one authoritative page per concern; do not duplicate JSON field lists across guides.

Need	Authoritative document
Commands, flags, examples	Command line guide
JSON shapes and exit codes (diff, stats, trace, manifest, export, import, and cross-command notes)	CLI JSON inventory
liel merge --format json fields and merge-specific exit semantics	CLI merge report
Which document owns which JSON surface (CI, MCP, viewer)	Machine-readable surfaces
Viewers and dashboards (no raw .liel parsing in the browser)	Viewer JSON contract
External vector stores alongside liel	Vector hybrid conventions
Optional per-label validation outside the core	Schema profiles (optional)

Document scope

Document	Concern	Read when you need to
Capability matrix	Features, CLI, MCP, docs by audience and value	Stakeholder overview in one table
Feature list	Public API and feature coverage	Check what liel provides
Reliability and failure model	Commits, recovery, failure modes, operational assumptions	Use liel as durable state
Benchmarks and file size notes	Local benchmark script and practical .liel size estimates	Interpret benchmark output or estimate memory-file size
Format spec	Byte-level .liel file layout	Build compatibility tooling or connectors
CLI merge report	liel merge --format json payload	CI, MCP, or scripts consuming merge previews
CLI JSON inventory	diff / merge / stats / manifest / export / import JSON and exit codes	Automation across CLI commands
Machine-readable surfaces	Index of contract owners for CI, MCP, viewers	Pick the right spec page
Viewer JSON contract	Stable inputs for tools that visualize memory	Build dashboards without embedding Rust
Vector hybrid conventions	Properties that reference external embeddings	Hybrid retrieval setups
Schema profiles (optional)	Optional label expectations for validators	Team linting, not core enforcement

This section’s format spec is the public English byte-layout reference. If a parallel maintainer copy exists in the repository for the same concern, keep both aligned in scope when editing.

---

Document	Content
Capability matrix	Stakeholder-oriented map (core, Python, CLI, MCP, docs)
Feature list	Quick reference of provided functionality
Reliability and failure model	What committed data means, how crash recovery works, and which failure modes are out of scope
Benchmarks and file size notes	How to read the benchmark script and practical .liel size estimates
Format spec	Canonical .liel byte layout
CLI merge report	Stable JSON fields for liel merge
CLI JSON inventory	Cross-command JSON and exit semantics
Machine-readable surfaces	Index of which doc owns which JSON contract
Viewer JSON contract	Approved inputs for visualization tools
Vector hybrid conventions	Embeddings in external stores
Schema profiles (optional)	Optional per-label checks