Checking a document before you rely on it

Checking a document before you rely on it

saphan doc check <file>
saphan doc check --family exec-status <file>
saphan doc check --family exec-status <file> --json

Every rule it applies is projected from the same key table the parser reads, so a check and the parser cannot disagree about the same document.

⚠ The two forms ask different questions, and the difference is deliberate.

• No --family is a question: "what is this, and is it well-formed?" An unrecognized H1 is not a failure — it exits zero, reports family none, and reports that nothing was measured.
• An explicit --family is a claim by you. Naming exec-status for a file with no # STATUS — <slug> H1 is a missing-H1 refusal. Same file, two exit codes, because two different questions were asked.

Exit codes: 0 valid, or family none · 1 the invocation itself was bad — an unreadable path, an unknown family · 2 measured and failed · 3 you asked with --require-checked, meaning "I am about to act on this answer", and the document could not be measured at all.

⛔ A passing check is not a claim that the work is right. It is the claim that the document is legible. Those are different facts, and treating the first as the second is the mistake this verb makes easy to avoid and cannot prevent.

Two neighbours:

• saphan channel ls <stream> — what the stream's channel currently holds.
• saphan grammar owner-block — the generated grammar of the fenced envelope a document carries when it puts something on a human's hand. It names, for every kind of element, when to use it, which keys are required, the rendering budget, and one example. An agent does not need a source checkout to read it.

The rules worth remembering after you close this page

1. The H1 names the stream, never the file. Keep the emitted one.
2. Manifests are nested dashes; prose lives on the key line. These are the two shapes that produce a complete-looking document holding nothing.
3. A state is one token, alone. Qualifications go in - note:.
4. Five writable state words for an agent, three writable verdicts for a reviewer. A word remembered from an older document is the word that gets refused.
5. An abstract over five lines is content nobody sees. Put the rest in the body the manifest names.
6. - artifacts: is what teardown reads. - evidence: is not. If it must survive the worktree, it goes in the manifest.
7. Every claim in - done: names its instrument. A gate cannot act on an opinion.