Reference

Header Reference

Header	Purpose	Example
@id	Identifier for the record (plain string)	@id prompt-001
@reply-to	Reply to another record by @id (threading)	@reply-to c1
@by	Attribution of who provided feedback	@by alice
@tag	Space-separated tags for categorization	@tag training batch-1
@input	Reference to input that produced the content	@input ./prompts/sunset.txt
@file	Reference to external content file (provenance)	@file ./images/photo.jpg

Header order in canonical form: @id → @reply-to → @by → @tag → @input → @file → unknown headers (alphabetical)

File-Level Header Reference

Header	Purpose	Example
%markback	Version declaration	%markback 2
%scope	Issues being checked (space-separated)	%scope correctness style
%covers	Glob pattern of files under review	%covers ./src/*.py

CLI Command Reference

Command	Purpose	Options
mb <file> "<feedback>"	Add feedback to a file	--by, --tag, --input
mb --lint <paths...>	Lint MarkBack files/directories	--json, --no-source-check, --no-canonical-check
mb --normalize <input>	Normalize to canonical V2 form
mb --list <paths...>	List records
mb --stats <paths...>	Show statistics
mb --convert <input>	Convert storage modes	--to (single, multi, compact)
mb --upgrade <files...>	Upgrade V1 files to V2	--dry-run
mb --init [path]	Create a .env template	--force

Configuration Keys (.env)

Key	Meaning
FILE_MODE	git (overwrite) or versioned (timestamped outputs)
DEFAULT_BY	Default value for @by header when adding feedback

Lint Error Codes

Code	Meaning
E001	Missing feedback (no <<< delimiter found)
E002	Multiple <<< delimiters in one record
E004	Content after <<< delimiter
E006	Malformed header syntax or invalid file encoding
E007	Invalid JSON after json: prefix
E008	Unclosed quote in structured attribute value
E009	Empty feedback (nothing after <<<)
E010	Missing blank line before inline content
E011	Invalid line/character range (end before start)
E012	Unclosed fenced feedback block (missing closing """)

Retired Error Codes (V1 only)

Code	V1 Meaning	V2 Status
E003	Malformed URI in @uri	Retired: @id has no format validation
E005	Content present when @source specified	Retired: @file + inline content now valid

Lint Warning Codes

Code	Meaning
W001	Duplicate @id within the same file
W002	Unknown header keyword
W003	@file referenced file not found
W004	Trailing whitespace on line
W005	Multiple blank lines
W006	Missing @id (record has no identifier)
W007	Paired sidecar file not found
W008	Non-canonical formatting detected
W009	@input referenced file not found
W010	V1 format detected (old header mapped to V2 equivalent)
W011	@reply-to points at an unknown @id or forms a cycle