Why only fenced blocks¶

docscheck flags one shape: inside a fenced code block, a command group followed by a concrete token that is not one of its subcommands. Everything else passes. That narrowness is not caution — it is what the measurements forced.

The obvious rule does not work¶

The natural first rule is: resolve every documented invocation against the command tree, and flag any that lands on a node with children. Run over the corpus that produced this module, it reported 15 problems. The real count was 3. All fifteen were false positives.

Twelve were a command group's own reference page naming the group in its title: frontmatter, its # heading, or its prose:

---
title: krites reset
---

# krites reset

Running `krites reset` on its own is an error, not a no-op.

None of that instructs anyone to run anything. A person types what is in a code block; they read the rest. Restricting the scan to fenced blocks removed all twelve.

The last three were synopses¶

The survivors were usage blocks on the group's own page:

krites docs
krites doctor
krites xmp <subcommand> [flags]

A bare group, or a group followed by a placeholder. Neither is the shape that breaks: what breaks is a group followed by a concrete argument, as in krites reset IMG_2043.CR2. Ignore bare groups, placeholders and flags and the false positives reach zero — with all three real defects still caught.

The problem that dissolved¶

There appears to be a hard question underneath this. Some groups run standalone and some error without a subcommand:

$ krites config      # runs, exit 0
$ krites reset       # ERRO reset requires a subcommand — exit 1

So surely the checker has to tell them apart, and surely that needs either an allowlist or executing the command?

Neither. Once you only flag a group followed by a token that is not one of its subcommands, the distinction stops mattering — that invocation fails whether or not the group runs bare. The question was an artefact of the wrong rule.

This matters more than it looks, because the alternative is unreliable. On one locally-built binary, krites docs exits 1:

ERRO failed to load documentation assets: file does not exist

That is a property of how the binary was built, not of what the docs say. A checker that reads behaviour changes its verdict with the build environment; a checker that reads structure does not. docscheck executes nothing.

What stays out of scope¶

Flags. A documented --shoot that no longer exists fails a reader identically, and the tree carries the flag set — but the extraction problem is materially harder (values, = forms, line continuations) and the false-positive budget here is zero.
Whether the prose is true. This checks that a command can run, not that the sentence around it describes what it does.
Executing your tutorials end to end. Strictly stronger, and a different piece of work with real fixture and runtime cost. This is the near-free surface check; they are complements.

The bar a check like this has to clear¶

False positives are what kill a gate. One that cries wolf gets bypassed, and then it is worse than nothing because it still looks like coverage. The measured result on the corpus that produced it: 57 files, 97 documented invocations, 0 false positives, and 3 of 3 real defects caught when the fix is reverted.