Documentation Map

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"]

Loading

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

Because nothing tests these pages, they carry risk that repository documentation does not. Two habits keep it 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.

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

Where next

• Development and Contributing: the validation gate and PR expectations.
• Home: the full page index.