<!-- generated by scripts/gen-reference.mjs; do not edit -->

Vault schema reference

Notes are Markdown files with YAML frontmatter. Unknown fields are preserved on read and write.

Common fields

Field	Type	Required	Default	Description
title	string	no	—	—
tags	string[]	no	[]	—
source	string	no	manual	"manual" for human-written notes, "agent:<name>" for notes approved from the inbox.
updated	string	no	—	—

layer notes

Stored in layers/.

Field	Type	Required	Default	Description
title	string	no	—	—
tags	string[]	no	[]	—
source	string	no	manual	"manual" for human-written notes, "agent:<name>" for notes approved from the inbox.
updated	string	no	—	—
type	"layer"	yes	—	Note type.
description	string	no	—	—

tech notes

Stored in tech/.

Field	Type	Required	Default	Description
title	string	no	—	—
tags	string[]	no	[]	—
source	string	no	manual	"manual" for human-written notes, "agent:<name>" for notes approved from the inbox.
updated	string	no	—	—
type	"tech"	yes	—	Note type.
kind	language | framework | library | tool | service | database	yes	—	—
layer	string | string[]	yes	—	—
language	string	no	—	—
version	string	no	—	Version of the tech the user's notes target, e.g. "19" or "2.7".
packages		no	—	Package names that identify this tech in manifests.
use_when	string[]	no	[]	—
avoid_when	string[]	no	[]	—
performs_best	string[]	no	[]	—
related	string[]	no	[]	—
practices	string[]	no	[]	—
checks	string[]	no	[]	—

practice notes

Stored in practices/.

Field	Type	Required	Default	Description
title	string	no	—	—
tags	string[]	no	[]	—
source	string	no	manual	"manual" for human-written notes, "agent:<name>" for notes approved from the inbox.
updated	string	no	—	—
type	"practice"	yes	—	Note type.
applies_to	string[]	no	[]	—
since	string	no	—	Start of the version range the note is valid for (inclusive).
until	string	no	—	End of the version range the note is valid for (exclusive).

check notes

Stored in checks/.

Field	Type	Required	Default	Description
title	string	no	—	—
tags	string[]	no	[]	—
source	string	no	manual	"manual" for human-written notes, "agent:<name>" for notes approved from the inbox.
updated	string	no	—	—
type	"check"	yes	—	Note type.
applies_to	string[]	no	[]	—
kind	test | lint | review | build	no	test	—
command	string	no	—	Optional shell command an agent can run to perform the check.
since	string	no	—	Start of the version range the check is valid for (inclusive).
until	string	no	—	End of the version range the check is valid for (exclusive).

profile notes

Stored in profiles/.

Field	Type	Required	Default	Description
title	string	no	—	—
tags	string[]	no	[]	—
source	string	no	manual	"manual" for human-written notes, "agent:<name>" for notes approved from the inbox.
updated	string	no	—	—
type	"profile"	yes	—	Note type.
description	string	no	—	—
use_when	string[]	no	[]	—
stack	map<string, string[]>	no	{}	layer id -> list of tech ids

project notes

Stored in projects/.

Field	Type	Required	Default	Description
title	string	no	—	—
tags	string[]	no	[]	—
source	string	no	manual	"manual" for human-written notes, "agent:<name>" for notes approved from the inbox.
updated	string	no	—	—
type	"project"	yes	—	Note type.
description	string	no	—	—
path	string	no	—	Absolute path of the project on disk.
status	active | paused | archived	no	active	—
profile	string	no	—	Profile id it started from.
stack	map<string, string[]>	no	{}	layer id -> tech ids
reason	string	no	—	—
lessons	string[]	no	[]	Short learnings for the vault.
last_checks	map<string, { status, at, duration_ms, output_tail }>	no	—	Results of the last basics check run, keyed by check id.

basics.json

Written by basics export in a project root and read by basics check.

{
  "stack": [
    "fastapi",
    "react"
  ],
  "targets": [
    "agents",
    "claude"
  ],
  "project": "my-app",
  "versions": {
    "fastapi": "0.115"
  }
}

Field	Type	Required	Default	Description
stack	string[]	yes	—	Tech ids exported for the project.
targets	agents | claude | cursor[]	yes	—	Agent files to write.
project	string	no	—	Id of the project note linked to this directory.
versions	map<string, string>	no	—	Version override per tech id.

pack.json

Manifest of a note pack, shipped in packs/<name>/pack.json.

{
  "name": "python-api",
  "version": "1.0.0",
  "description": {
    "en": "Python API stack notes",
    "es": "Notas de stack para APIs en Python"
  },
  "requires": [
    "core-layers"
  ],
  "languages": [
    "en",
    "es"
  ]
}

Field	Type	Required	Default	Description
name	string	yes	—	Pack id, lowercase letters, digits and dashes.
version	string	yes	—	Dot-separated version compared numerically.
description	map<string, string>	yes	—	Short description per language.
requires	string[]	no	[]	Packs installed before this one.
languages	string[]	yes	—	Languages the pack has notes for (at least one).

basics.vault.json

Committed at the vault root. basics init writes it; old vaults without it keep working.

{
  "schemaVersion": 1
}

Field	Type	Required	Default	Description
schemaVersion	integer	yes	1	Vault schema version written by this build. A newer value means the vault needs a newer basics.