Reference
Header Reference
| Header | Purpose | Example |
|---|---|---|
@uri | Unique identifier for the record | @uri local:prompt-001 |
@by | Attribution of who provided feedback | @by alice |
@prior | Reference to input that produced the content | @prior ./prompts/sunset.txt |
@source | Reference to external content file | @source ./images/photo.jpg |
Header order in canonical form: @uri → @by → @prior → @source → unknown headers (alphabetical)
CLI Command Reference
| Command | Purpose | Options |
|---|---|---|
markback init [path] | Create a .env template | --force, -f |
markback lint <paths...> | Lint MarkBack files/directories | --json, -j, --no-source-check, --no-canonical-check |
markback normalize <input> [output] | Normalize to canonical form | --in-place, -i |
markback list <paths...> | List records | --json, -j |
markback convert <input> <output> | Convert storage modes | --to, -t (single, multi, compact, paired) |
markback workflow run <dataset> | Run editor/operator workflow | --prompt, -p, --output, -o, --env, -e |
markback workflow evaluate <results> | Show evaluation summary | --json, -j |
markback workflow prompt <results> | Extract refined prompt | --output, -o |
Configuration Keys (.env)
| Key | Meaning |
|---|---|
FILE_MODE | git (overwrite) or versioned (timestamped outputs) |
LABEL_SUFFIXES | Comma-separated suffixes for paired label files |
EDITOR_API_BASE | Base URL for editor model API |
EDITOR_API_KEY | API key for editor model |
EDITOR_MODEL | Model name for editor |
EDITOR_MAX_TOKENS | Max tokens per editor call |
EDITOR_TEMPERATURE | Sampling temperature for editor |
EDITOR_TIMEOUT | HTTP timeout (seconds) |
OPERATOR_API_BASE | Base URL for operator model API |
OPERATOR_API_KEY | API key for operator model |
OPERATOR_MODEL | Model name for operator |
OPERATOR_MAX_TOKENS | Max tokens per operator call |
OPERATOR_TEMPERATURE | Sampling temperature for operator |
OPERATOR_TIMEOUT | HTTP timeout (seconds) |
POSITIVE_LABELS | Comma-separated labels treated as positive |
NEGATIVE_LABELS | Comma-separated labels treated as negative |
Lint Error Codes
| Code | Meaning |
|---|---|
E001 | Missing feedback (no <<< delimiter found) |
E002 | Multiple <<< delimiters in one record |
E003 | Malformed URI in @uri header |
E004 | Content after <<< delimiter |
E005 | Content present when @source is specified |
E006 | Malformed header syntax or invalid file (UTF-8, missing file) |
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 reference format (must be :line or :start-end) |
E012 | Line number must be a positive integer |
E013 | End line must be greater than or equal to start line |
Lint Warning Codes
| Code | Meaning |
|---|---|
W001 | Duplicate URI within the same file |
W002 | Unknown header keyword |
W003 | @source file not found |
W004 | Trailing whitespace on line |
W005 | Multiple blank lines |
W006 | Missing @uri (record has no identifier) |
W007 | Paired feedback file not found |
W008 | Non-canonical formatting detected |
W009 | @prior file not found |
W010 | Line reference exceeds file line count |