docs: streamline README and split detailed guides

scripts/check-docs.sh

@@ -2,22 +2,37 @@
 set -eu
 
 repo=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
-readme="$repo/README.md"
 
-test -s "$readme"
-for text in \
-  '## Install' 'go install ./cmd/proxyctl' '## First use and Profiles' \
-  '## Shell integration' 'Shell' 'APT' 'Docker daemon' \
-  'Docker containers/builds' 'GNOME' '## Target states' 'Enabled' \
-  'Disabled' 'External' 'Drifted' '## Permissions, sudo, and restarts' \
-  'proxyctl doctor' 'proxyctl reset' 'proxyctl shell uninstall' \
-  'no telemetry' 'automatic update checks' 'proxy-connectivity tests' \
-  'does **not** manage or supervise proxy processes' 'Support is limited'
-do
-  grep -Fq "$text" "$readme" || {
-    echo "README is missing required documentation: $text" >&2
-    exit 1
-  }
-done
+require_text() {
+  file=$1
+  shift
+  test -s "$file"
+  for text
+  do
+    grep -Fq "$text" "$file" || {
+      echo "$file is missing required documentation: $text" >&2
+      exit 1
+    }
+  done
+}
 
-printf 'README documentation contract passed\n'
+require_text "$repo/README.md" \
+  '## Install' 'go install ./cmd/proxyctl' '## Quick start' \
+  '## Shell integration' 'proxyctl doctor' 'proxyctl reset' \
+  'no telemetry' 'docs/user-guide.md' 'docs/security.md' 'docs/development.md'
+
+require_text "$repo/docs/user-guide.md" \
+  '## Profiles' 'Protocol Probe' '## Target states' 'Enabled' 'Disabled' \
+  'External' 'Drifted' 'Shell' 'APT' 'Docker daemon' \
+  'Docker containers/builds' 'GNOME' 'NO_COLOR'
+
+require_text "$repo/docs/security.md" \
+  'proxyctl never starts `sudo`' 'Configuration recovery' \
+  'no automatic update checks' 'does **not** manage or supervise proxy processes' \
+  'Support is limited'
+
+require_text "$repo/docs/development.md" \
+  'go test ./...' 'go vet ./...' 'test-hermetic.sh' \
+  'test-release.sh' 'verify-clean-machine.sh' 'SHA256SUMS'
+
+printf 'documentation contract passed\n'