Frontmatter reference

The YAML block between the two --- lines at the top of every .dlm document. Validated with Pydantic in dlm.doc.schema (extra="forbid", frozen=True) — unknown keys or wrong types fail fast with a file:line:col error.

Minimum required frontmatter

---
dlm_id: 01HRZYQ2X0MB5K4VN7E9DNT5GH
base_model: smollm2-135m
---

dlm_id is a 26-character Crockford base32 ULID. dlm init generates it; don't edit it by hand.

base_model is either a registry key or hf:org/name:

The shipped registry is broader than this quick-start table. Current additions include:

• 2026 text-family refresh rows: qwen3-1.7b, qwen3-1.7b-thinking, qwen3-4b, qwen3-8b, llama-3.3-8b-instruct, phi-4-mini-reasoning, gemma-2-2b-it, gemma-2-9b-it, smollm3-3b, olmo-2-7b-instruct, and mixtral-8x7b-instruct.
• Vision-language rows: paligemma-3b-mix-224, qwen2-vl-2b-instruct, internvl2-2b, internvl3-2b, and mistral-small-3.1-24b-instruct.
• Audio-language row: qwen2-audio-7b-instruct.

Off-registry bases use hf: prefix, e.g. base_model: hf:mistralai/Mistral-7B-Instruct-v0.3. dlm init runs a compatibility probe; failures abort with a clear diagnostic.

Full frontmatter

---
dlm_id: 01HRZYQ2X0MB5K4VN7E9DNT5GH
dlm_version: 1                    # bumped by `dlm migrate`; default: 1
base_model: qwen2.5-1.5b
system_prompt: |
  You are a concise assistant.
training:
  adapter: lora                   # or qlora (CUDA only)
  lora_r: 8                       # 1..256
  lora_alpha: 16
  lora_dropout: 0.05              # 0.0..0.5
  target_modules: auto            # or a list[str]
  sequence_len: 2048              # 64..32768
  micro_batch_size: auto          # or a positive int
  grad_accum: auto                # or a positive int
  learning_rate: 2e-4
  num_epochs: 3
  optimizer: adamw_torch          # or adamw_bnb_8bit / paged_adamw_8bit
  lr_scheduler: cosine            # or linear / constant
  warmup_ratio: 0.1               # 0.0..0.5
  # precision: fp16               # optional override; default lets the doctor pick
  seed: 42
export:
  default_quant: Q4_K_M           # or Q5_K_M / Q6_K / Q8_0
  default_temperature: 0.2        # optional; overrides dialect default
  default_top_p: null             # optional; null keeps dialect default
---

Field-by-field

Top-level

training

training.gate — GateConfig

Learned adapter routing. A small MLP trained post-SFT that maps a prompt embedding to per-adapter weights, replacing the hand-set --adapter-mix for the dlm prompt path.

Enabling gate on a document without training.adapters (or with only one adapter) is refused at parse time — a router over a single adapter has nothing to route between. See docs/cookbook/learned-adapter-gate.md for the full workflow + Ollama-export fallback semantics.

training.audio — AudioConfig

Opt-in knobs for audio-language training. Only consulted when the base_model is audio-language (e.g. qwen2-audio-7b-instruct). Defaults preserve the pre-v12 contract.

Requires either soxr (pip install dlm[audio] pulls it in) or scipy to be importable when auto_resample: true; otherwise the preprocessor/collator raises AudioResampleUnavailable at first mismatched decode rather than training on the wrong rate.

training.cache — CacheConfig

Per-document knobs on the tokenized-section cache at ~/.dlm/store/<dlm_id>/tokenized-cache/. Defaults match the behavior pre-v9 so upgrading a doc is a no-op.

The CLI --no-cache flag and the DLM_DISABLE_TOKENIZED_CACHE=1 env var both override enabled: true for a single invocation. See the cache cookbook for sizing advice.

training.sources[] — SourceDirective

One entry per external root to ingest. Paths resolve relative to the .dlm file's parent when not absolute; ~ expands to $HOME.

Behavior:

• File enumeration is deterministic. Lexicographic sort on the resolved path list; identical trees on identical OSes produce identical Section order.
• Binary files are skipped (NUL byte in the first KiB — the standard grep heuristic). Skip count is recorded in the training summary.
• UTF-8 decode failures are skipped, not fatal. Use exclude for known-non-UTF-8 formats.
• Each ingested file becomes a PROSE section whose content is prefixed with # source: <relpath>\n\n. The path prefix ensures two files with identical bodies produce distinct section_ids — the replay corpus tracks per-file identity, not per-content.
• Integration is seamless with in-body sections. The CPT path, replay corpus, content-hash diff, and deterministic train/val split all treat directive-sourced sections identically.

Example:

training:
  sources_policy: permissive
  sources:
    - path: ~/code/quillstone-protocol
      include: ["**/*.py", "**/*.rs"]
      exclude: ["tests/**", "**/__pycache__/**"]
      max_bytes_per_file: 65536
      max_files: 5000
    - path: ~/notes/research.md

After dlm train, the training summary JSON carries a source_directives: [...] array with per-source file counts, byte totals, and skip breakdowns. dlm show --json reports the same under training_sources.

Secrets warning: directive ingestion has no implicit exclude list. Add explicit exclude: ["**/.env", "**/credentials*", ...] or use sources_policy: strict + a curated subtree to avoid training on .env, private keys, or other sensitive files that happen to live in your codebase.

export

Migrations

When a new version bumps dlm_version (e.g., adding a field), dlm migrate runs the registered migrators in order and rewrites the frontmatter in place. See Sprint 12b for the migration framework.

The parser refuses to load a document whose dlm_version exceeds the running CLI's CURRENT_SCHEMA_VERSION:

error: tutor.dlm:2:14 — dlm_version 2 is newer than this CLI supports (1).
       Upgrade dlm to continue.