docs(user-guide,architecture): regenerate samples from real output (#97)

[luongnv89]

Closes #97

Summary

docs/USER_GUIDE.md was left out of the file set of #72 (PR #95) and still
carried sample output that no code path emits. Every fenced output block is now
spliced from an actual run against the repository's smallFlows.pcap — the same
method PR #95 used for the other docs — rather than hand-edited. The two
docs/ARCHITECTURE.md identifier fixes the issue asked for are folded in.

Beyond the three defects the issue names, regenerating the file surfaced a
fourth fabrication and a broken-command class that acceptance criterion 5 forces
into scope: a whole "PCAP Statistics" section for a feature that does not exist,
and every example using the pre-subcommand form (./mmtReader -t ...), which
exits 0 but only prints the help screen and analyzes nothing.

Approach

Option 2 (balanced): fix the fabricated output, make every documented command
actually runnable, and stop contradicting docs/CONFIG.md.

The blocks were not typed. A generator read the captured stdout of each
documented command and spliced contiguous verbatim slices into the page; long
tables are cut at an explicit ... row with the true row count stated, and the
JSON sample is the real document with only its two arrays shortened (key order,
indentation and every value untouched, and it still parses).

Decision Record

• Root cause: docs/USER_GUIDE.md has not been touched since docs(doc-manager): reconcile all docs to code + generate missing docs #33 (54da1d2).
  PR docs(build,test): align README and DEVELOPMENT with the real build (#72) #95 corrected README/DEVELOPMENT/TESTING/PLAYBOOK/AGENT_ENVIRONMENT against
  the real build but deliberately excluded this file, and PR fix(cli): honor json from config file and MMTREADER_JSON (#96) #98 (json option from config file and MMTREADER_JSON env var are silently ignored #96) then
  changed config/env JSON behaviour without revisiting it. The guide therefore
  documents a tool several releases behind the one in the repo — an uppercase
  TCP.HTTP.Google path format, stat labels cli/output.c never prints, a JSON
  schema predating both the protocol_paths[] split and the version object
  from [4.2] Introduce project version distinct from SDK version #70, and a PCAP-statistics section for a feature that was never
  implemented.
• Options considered: Option 1 — fix only the four fabricated output blocks
  plus the ARCHITECTURE.md naming; Option 2 — that, plus make every command
  runnable and align the config/env sections with docs/CONFIG.md; Option 3 —
  that, plus troubleshooting, option tables, CHANGELOG and a cross-doc sweep.
• Options rejected: Option 1 — provably fails acceptance criterion 5, since
  the untouched examples still omit the subcommand and point at a capture.pcap
  that exits 2. Option 3 — roughly doubles the review surface for a
  priority: low documentation issue, and even then leaves the same fabrication
  standing in README.md and PLAYBOOK.md.
• Selected option: Option 2 — balanced. Two Option 3 items were pulled in
  because leaving them out would have been self-inflicted: docs/ARCHITECTURE.md
  repeated the same PCAP-statistics fabrication being deleted from the guide (and
  that file is already in the diff), and both docs(build,test): align README and DEVELOPMENT with the real build (#72) #95 and fix(cli): honor json from config file and MMTREADER_JSON (#96) #98 set the house
  convention of a CHANGELOG entry for doc corrections.
• Residual risk: analyze --help advertises -i, --interface <iface> as
  "alternative to -t", but the parser rejects it — the tool's own help text is
  wrong. It is reproduced verbatim here (it is real output) with a note flagging
  the discrepancy; fixing the help string is a code change and belongs in its own
  issue. The identical fabricated PCAP-statistics block still stands
  in README.md:584 and docs/PLAYBOOK.md:469-471; both are outside this
  issue's named file set and worth a short follow-up. Sample values (packet
  counts, the SDK build hash, the banner's build timestamp) are environment- and
  build-specific, and there is no automated test pinning the docs to real output,
  so this class of drift can recur — a doc-verification test group would prevent
  it but would change the documented "14 numbered test groups" everywhere and was
  left out of scope.

Analyzed at: docs/97-regenerate-user-guide-samples @ 913ef67 (2026-08-27), based on main @ ccbb631

Changes

File	Change
docs/USER_GUIDE.md	Every sample block regenerated from real output; all commands given their analyze/capture subcommand and pointed at smallFlows.pcap; fabricated "PCAP Statistics" section and is not an Ethernet error removed; troubleshooting messages spliced verbatim; option tables completed with -b, -c and -F; config/env sections aligned with docs/CONFIG.md
docs/ARCHITECTURE.md	insert_proto_info() → proto_info_insert() (cli/output.c:104, and the list is doubly-linked); engine_print_stats_ex() attributed to core/engine.c:281; removed the Output Sequence bullet for the non-existent PCAP-statistics section; corrected the online-mode "Ethernet-only" claim, which contradicted capture.c's 802.11 handling
CHANGELOG.md	### Documentation entries under [Unreleased] for both files

Test Results

• Unit tests: 299 asserts passed (groups 5–11, incl. 5b)
• Integration tests: 52 / 52 CLI checks passed (group 12); 6 / 6 SDK checks (group 14)
• E2e tests: n/a
• Build: passed, warning-free under -Wall -Wextra
• Docs verification: 198 pasted output lines matched against freshly captured tool output; 11 / 11 runnable documented commands exit 0
• QA cycles: 2

QA ran one independent reviewer pass on top of direct verification, and it
earned its keep: it caught a false claim this PR had introduced — that input
mode follows the -t/-i flag rather than the subcommand, so analyze -i
would capture live. It does not. Both input flags are gated symmetrically and
analyze -i exits 2 with Error: -i/--interface is for 'capture' only
(cli/parse.c:394; capture -t is rejected the same way at :380). Four
places that leaned on the wrong reading were corrected, and a second reviewer
pass then confirmed the fix and returned clean. A slower first-cycle reviewer
additionally caught that docs/ARCHITECTURE.md still called live capture
"Ethernet-only (DLT_EN10MB check)" — contradicting capture.c and this PR's
own new USER_GUIDE text. No datalink is ever rejected: pcap_datalink() is read
at mmtReader.c:195, 802.11 is converted at capture.c:289-312, and anything
else passes through. Fixed, and British spellings I had introduced were
normalized to the repo's American convention. Beyond the acceptance criteria, every author-written claim in the guide
was checked against the source or by running the tool: -b is consumed only on
the live path (mmtReader.c:170-187); analyze prints no INFO: lines; input
mode follows -t/-i rather than the subcommand (cli/parse.c:391,401), so
analyze -i really does capture live; -x/-y/-z share one optstring
(cli/parse.c:622) and work with both subcommands; the banner goes to stdout in
text mode and stderr under --json; pcap_stats() is called nowhere in the
source or the binary; capture.c converts 802.11 as well as Ethernet; and the
precedence chain was exercised end to end (config json=1 + MMTREADER_JSON=0
→ text; config json=0 + --json → JSON; MMTREADER_JSON=1 + --text →
text). Markdown fences balance and the single relative link resolves.

No C source changed, so the suite is unaffected; it was run to satisfy criterion 6.
make clean >/dev/null && make test exits 0 and ends All tests passed! with the
single tolerated root-gated skip (SKIP: live capture on 'lo' unavailable).

Acceptance Criteria Verification

Criterion	Status	Evidence
Every sample output block in docs/USER_GUIDE.md is reproduced by running the documented command against smallFlows.pcap and pasting real output	pass	Blocks are spliced by a generator from captured stdout, never typed. Independently re-verified: every one of the 198 non-elision lines in the output blocks is literally present in freshly re-run tool output.
grep -n "TCP.HTTP" docs/USER_GUIDE.md is empty	pass	Returns no lines (exit 1).
The JSON sample shows the current schema, including version as an object with mmtreader and mmt_dpi keys	pass	Sample is the real analyze -t smallFlows.pcap -a -j -s document with only its arrays shortened: version{mmtreader,mmt_dpi}, input_stats, protocol_paths[], protocols[], anomalies[]. Still parses as JSON.
docs/ARCHITECTURE.md names proto_info_insert() and attributes engine_print_stats_ex() to core/engine.c	pass	docs/ARCHITECTURE.md:165,168 name proto_info_insert() (cli/output.c:104); line 176 reads core/engine.c:281 (core/engine.c:281).
Every command printed in docs/USER_GUIDE.md runs verbatim and exits 0	pass	All 11 runnable commands extracted from the ```bash blocks were executed verbatim from the repo root: 11 pass, 0 fail. The 4 remaining are sudo … capture -i eth0 live-capture examples, root-gated exactly like the suite's own tolerated skip; usage synopses with placeholders were moved out of bash fences so they are no longer presented as runnable.
make clean >/dev/null && make test exits 0, 0 failures (1 tolerated root-gated skip)	pass	Exit 0, ends All tests passed!, 52/52 CLI checks, 6/6 SDK checks, 0 failures, 1 skip (live capture on 'lo').