--json. Under that flag a command prints exactly one object on
stdout, prints nothing else on stdout, turns colour off and sends every log line to stderr. An
error prints the envelope too. This page is the short contract an agent needs. The per-command
payloads are in the CLI reference.
The envelope
A finding row
Every row offindings.items[] has the same shape on every command, so an agent can dispatch on the
rows alone without reading the per-command payload.
A row that judges nothing carries the passing code
NOTE, so code and label are strings on
every row and a reader never meets a null code.
An error
Theerror object is filled by whatever raised the error, so a slot it does not know is null.
In text mode the same error prints as
error[CONFIG]: ... on stderr, so the code is readable
without --json.
Exit codes
The rule an agent follows is one line. A non-zero exit with
error null is a finding, and the agent
may fix the project and run the command again. A non-null error is an error, and the agent stops
and tells the person.
Write the trigger as error == null rather than as “exits 1”, because a broken machine can exit
non-zero for reasons that are not the project’s fault.
Watching a build
decktalk build appends one JSON Lines object per event to build/progress.jsonl, relocatable with
--progress. Each row carries ts, stage, stage_index, stage_count, section, event,
detail and pid, and event is one of start, done, skip and fail.
Poll decktalk status --json rather than tailing that file. Its run object is null when no build
is running, and otherwise carries pid, started, stage, sections_done, sections_total and
alive.
Reading what a project has
status.narration is the narration clock that build/narration/takes.json gives: exists,
estimated, total_seconds, and one sections[] row per spoken section with key, title,
start, end and duration. estimated is true while the takes are placeholders a run without
voice wrote.
Each status.sections[] row carries key, kind, source, recorded, cut and stale. stale
is null while the recording on disk still matches the project, and otherwise one sentence saying why
it does not, which is the same rule record uses to decide what to record again.