Exit codes

Exit codes are a contract: values are never reused and never change meaning.

Code	Name	Meaning
0	success	The command did what it was asked to do.
1	context integrity failure	The repository context is not in a valid state.
2	invalid CLI usage	The command could not run as invoked.
3	unsupported context schema	The context declares a schema this build cannot read.
4	internal failure	A bug in Syngraphe.

0 — success

• init applied its plan, completed a --dry-run, or found nothing to do.
• status always exits 0; it reports rather than judges.
• check found no errors — and no warnings, when --strict was passed.
• stats produced its report, including when the advisory budget is exceeded.
• A document command created or listed documents, or completed a --dry-run.

1 — context integrity failure

Something about the repository context is wrong and a human has to decide what to do.

• check found at least one error, or a warning under --strict.
• init built a plan containing conflicts: a hand-edited managed block, duplicate blocks, unbalanced markers, or a file that cannot be managed safely — including one that is not valid UTF-8. Nothing was written.
• init found a .context/ that is not a Syngraphe context, or a manifest that does not parse.
• A document command found its name already taken (letter case ignored), or stats or a document command found no usable context.
• An apply found the repository changed after planning: a destination another process created, a file edited meanwhile, or a file that could not be moved aside to verify it. Nothing was overwritten.

2 — invalid CLI usage

The command never really started.

• Not inside a Git repository.
• An unknown command, an unknown option, or a missing argument.
• --json on a mutating command without the required explicit --dry-run.
• A path that cannot be written safely — outside the repository root, or through a symlink.
• An invalid document name or title, an invalid --budget, a scope that is not an existing directory in this repository, or --all together with --scope.

--help and --version are successful outcomes and exit 0.

3 — unsupported context schema

.context/manifest.json declares a schemaVersion this build does not support, so nothing else it could report about the context would be trustworthy.

Emitted by init, check, stats and the document commands, and it takes precedence over 1 in check. The fix is to upgrade Syngraphe — never to lower the number in the manifest, which changes the declaration without changing the files.

4 — internal failure

An unexpected error escaped a command. Syngraphe prints Internal Syngraphe failure. and the stack trace.

This is a bug. The stack trace and the output of syngraphe check --json are what a report needs.

Handling them in a script

#!/usr/bin/env bash
set -euo pipefail

if syngraphe check --strict; then
  echo "context ok"
else
  case $? in
    1) echo "context needs attention"; exit 1 ;;
    3) echo "upgrade syngraphe: this repository uses a newer context schema"; exit 1 ;;
    *) echo "syngraphe could not run"; exit 1 ;;
  esac
fi

Distinguishing 3 is the one that pays off: it is the only code whose fix is on the tooling side rather than in the repository.