docs: define a single-source-of-truth strategy for CLI documentation

[hyperfinitism]

Background

The current snpguest documentation structure has become difficult to maintain.

Historically, the CLI has been documented in multiple places, especially:

• README.md
• docs/snpguest.1.adoc

As seen in #139, these documents can easily drift from the actual Clap-defined CLI: subcommands may be omitted, flag descriptions may become inaccurate, and synopsis/help text may no longer match the implementation. Keeping multiple handwritten representations of the same CLI API in sync is costly and error-prone.

In #151 I explores a different direction:

• generate a concise README.md from crate-level Rustdoc via cargo rdme
• improve Rustdoc coverage across the codebase
• enforce doc consistency in CI

That approach improves maintainability, but it also exposes an important distinction:

• the Rust crate API vs. the CLI API

Rustdoc is a natural fit for Rust-facing APIs and internal/module-level technical documentation, but it is not necessarily the best canonical format for the full command-line interface of a multi-subcommand CLI tool.

Problem

We likely need to separate the following documentation concerns more clearly:

1. README: short project overview, installation, quick-start, and pointers to deeper docs
2. CLI reference: the complete command-line API (commands, flags, arguments, synopsis, global options)
3. Tutorial docs: usage examples, regular and extended attestation flows, platform-specific caveats, technical notes, and so on

Trying to make one format serve all three roles has led to either duplication or awkward documentation structure.

Options

Option A: Keep handwritten README + handwritten AsciiDoc/manpage source

Pros:

• maximum editorial control
• easy to write narrative docs

Cons:

• duplicates the CLI API in multiple places
• high maintenance cost
• prone to drift

Option B: Generate README from Rustdoc (cargo rdme) and use Rustdoc for detailed docs

Pros:

• reduces duplication between source and README
• keeps high-level crate docs close to the code
• easy to validate in CI

Cons:

• mixes Rust API documentation and CLI documentation
• Rustdoc is not an ideal primary format for a complete CLI reference
• can blur the distinction between crate internals and user-facing command semantics

Option C: Use Clap as the source of truth for the CLI API, generate man pages from it, and keep longer guides as separate docs

Concretely:

• keep README.md short and focused (generated by cargo-rdme as Option B)
• improve (enhance) Clap's help messages
• generate man pages from Clap (e.g. via clap_mangen) as the canonical CLI reference
• write detailed docs manually under docs/*.md
• retire the handwritten .adoc CLI reference if the generated man page replaces it sufficiently

Pros:

• the full CLI API comes directly from the implementation
• avoids duplicating command/flag definitions by hand
• keeps README concise
• separates reference docs from conceptual guides more cleanly

Cons:

• requires deciding how generated man pages are built, stored, and shipped
• some examples and explanatory content still need manual docs
• may require a small docs-site/readme restructuring

Proposed direction

My current impression is that Option C is the cleanest long-term structure:

• Clap help/manpage generation for the authoritative CLI reference
• README for overview + quick-start only
• docs/*.md for detailed examples, technical explanations, attestation workflows, and caveats
• remove or deprecate the handwritten AsciiDoc CLI reference once the generated reference is in place

This would also keep the "single source of truth" principle where it matters most: the CLI API should come from the Clap definitions, not from duplicated prose.