Network Doctor

Documentation Map

Where documentation lives, and why. Read this before adding documentation anywhere, including to this wiki.

The rule

If correctness depends on the documentation changing in the same commit as the code, the authoritative version stays in the repository.

Everything else follows. The wiki may explain a concept and link to the authoritative source; it must not become a second exhaustive copy that can drift without anything noticing.

The failure mode this prevents is specific and easy to reach: a wiki page that lists every flag, gets edited through the web UI six months later by someone who did not touch the code, and quietly disagrees with the binary. Nothing tests a wiki page. That is the whole reason the boundary is drawn where it is.

What is authoritative, and where

Material Lives in Why
Exact netdoc flags, defaults, target grammar netdoc --help, packaging/netdoc.1 Generated from the flag set; the man page ships with the package
Exact netdoc-sim commands, flags, exit codes netdoc-sim help, packaging/netdoc-sim.1, packaging/completions/* Tested for exact agreement with the real command
Install commands per platform README.md Changes with releases and packaging
Probe table, JSON schema, verdict and exit-code tables README.md Changes with the probe implementations
The validation gate README.md#tests Pins exact tool versions; CI and the gate skill both point at it
Package layering rules, PR expectations CONTRIBUTING.md Ships in tagged releases and offline source trees
Simulator setup, scenario schema, fault semantics, evidence fields, campaigns, hunts, triage, the challenge contract docs/simulation.md Every part of it changes with the code beside it
Scenario inventory netdoc-sim scenarios A hand-written list is a list that goes stale
Starter packs, authored cases, answer vocabulary netdoc-sim starters / authored / the in-session menu Same reason
Fixed probe endpoints internal/diagnostic + the scenario aliases that claim them Drift is caught by the healthy canary
Package layering architecture_test.go Enforced, not described
Vulnerability reporting SECURITY.md Must be present in every checkout

What this wiki owns

Explanation, orientation, and worked reasoning:

  • Why the probe graph has independent branches, and what each split buys.
  • How to read a verdict and turn it into a next action.
  • Conceptual architecture: package boundaries and the two data flows.
  • Conceptual walkthroughs of Challenge Mode, hunts, and triage.
  • Troubleshooting and FAQ: behaviour that surprises people.
  • Navigation to the authoritative sources above.

Where a page states a technical fact, it states it as understanding rather than as a specification, and points at the tested source for the exact values.

Deliberate non-duplications

Things a wiki naturally wants to include, and why these pages do not:

No flag reference. netdoc --help and netdoc-sim help print every flag with its default, and both are checked against the man pages and all six shell completion files. A wiki copy would be a fifth surface with no test behind it.

No scenario list. netdoc-sim scenarios prints the current one, and the README already says so explicitly.

No literal generated challenge ids. The repository has a test, TestCurrentChallengeExamplesUseCurrentGeneration, that checks every challenge id example in the README, docs/simulation.md, the Dockerfile, cmd/netdoc-sim/challenge.go, the man page, and the CLI help against the current generation, and fails if one is stale or does not resolve. It cannot see this wiki. So the wiki names id versions and shapes, and directs readers to netdoc-sim challenge / authored for real ones.

No answer vocabulary. The in-session menu prints it, and duplicating it would be a partial spoiler as well as a drift risk.

No install command block. Taps, buckets, repository URLs, and package names change with releases; the README is what release automation and the maintainer keep current.

No exit-code table. Both binaries print theirs, and the README has them.

Why nothing was moved out of the repository

The audit that produced this wiki found no repository document that should be relocated, and the reasons are concrete rather than conservative:

  • README.md carries a challenge-id example asserted by cmd/netdoc-sim/packaging_test.go, and is linked by docs/simulation.md, CONTRIBUTING.md, and the repository’s gate skill (via #tests). It is also the repository landing page and the only documentation a go install user reliably sees.
  • docs/simulation.md is referenced by path or anchor from packaging/netdoc-sim.1, the Dockerfile’s org.opencontainers.image.documentation label, internal/simulation/challenge.go, internal/simulation/scenarios/healthy.yaml, packaging_test.go, and the same challenge-id test. Moving it would break a shipped container label and several source cross-references.
  • CONTRIBUTING.md is linked from the README and from GitHub’s contribution UI, and is correct for whichever tag you checked out, a property a single always-latest wiki cannot have.
  • Man pages and completions are packaged artefacts and are test-enforced against the real CLI.

A tagged release, an offline source tree, and a distribution package all need to carry their own documentation. A wiki has exactly one version, always the latest, which is right for explanation and wrong for reference.

Adding documentation: which surface?

graph TD
  START["New documentation"] --> Q1{"Would it be wrong<br/>if the code changed<br/>and it did not?"}
  Q1 -->|Yes| Q2{"Is it a flag,<br/>default, or exit code?"}
  Q1 -->|No| Q4{"Is it explanation,<br/>orientation, or a<br/>worked example?"}
  Q2 -->|Yes| CLI["CLI help + man page<br/>+ completions<br/>all three, tests enforce it"]
  Q2 -->|No| Q3{"Simulator internals?"}
  Q3 -->|Yes| SIM["docs/simulation.md"]
  Q3 -->|No| RM["README.md"]
  Q4 -->|Yes| WIKI["This wiki"]
  Q4 -->|No| CODE["A comment beside the code"]

One extra rule for the left branch: adding a netdoc-sim flag or command means updating the man page and all six completion files in the same commit. TestShippedSurfacesDeclareExactlyTheRealCommands and its per-flag sibling will fail the build otherwise, which is the mechanism working, not an obstacle.

Keeping this wiki honest

Most of a wiki is explanation, and nothing can test explanation. Two habits keep the untestable part small:

  1. Link, do not copy. Every exact value should be one click from its tested source.
  2. Prefer statements that survive change. “The row never falls back to port 53” is a design invariant. “The default timeout is 4 seconds” is a value that will move, so point at netdoc --help instead.

Quoting what netdoc prints

Sentences netdoc actually prints are the exception, and those are checked. Put <!-- netdoc-output --> immediately before the quotation:

<!-- netdoc-output -->
*"Online via the environment proxy: direct egress is blocked (proxy-only
network)."*

cmd/docsite reads the strings internal/diagnostic/diagnosis.go builds, which is the file that decides every summary and verdict detail netdoc prints, and fails the site build when a marked quotation is not one of them. That runs on every push and on the gollum trigger, so editing a page in the browser checks it too. Markdown line wrapping is not significant. A … inside the quotation stands for text left out, either a hostname netdoc interpolates or a clause the point does not need, so quote the part that has to stay true and elide the rest.

The check runs in the other direction as well: an unmarked quotation long enough to be netdoc’s own text also fails, so a verified sentence cannot be quietly demoted to prose by deleting one line.

Deliberately outside the contract, because neither is what the program prints: the sketched row blocks in Understanding Your Diagnosis, which use invented hostnames and no colour, and fenced blocks generally, which hold commands to type rather than output to expect.

If you find this wiki disagreeing with the repository, the repository is right, and the wiki has a bug worth an issue.

Where next

This page has one editable copy: edit it at the source.