Documentation Audit Commands

Commands for auditing documentation consistency, finding outdated references, and maintaining documentation health across the domus-* ecosystem.

Quick Health Check

Run from any domus-* repo root

# Count runbooks and their sizes
ls -la docs/asciidoc/modules/ROOT/pages/runbooks/*.adoc 2>/dev/null | wc -l
wc -l docs/asciidoc/modules/ROOT/pages/runbooks/*.adoc 2>/dev/null | tail -1

Hostname/IP Audits

Verify IPs Against DNS (Do This First)

# Verify documented IPs match actual DNS
for host in ise-01 ise-02 vault-01 home-dc01 bind-01 k3s-master-01; do
  ip=$(dig +short ${host}.inside.domusdigitalis.dev)
  echo "${host}: ${ip:-NOT FOUND}"
done

Find Deprecated Hostnames

# Find certmgr-01 references (deprecated → vault-01)
grep -rn "certmgr-01" docs/ --include="*.adoc" | wc -l
grep -rn "certmgr-01" docs/ --include="*.adoc"

# Find hardcoded IPs that should be attributes
grep -rn "10\.50\.1\." docs/ --include="*.adoc" | grep -v "antora.yml" | head -20

Verify Attribute Usage

# List all attributes in antora.yml
awk '/^  [a-z].*:/ && !/^  -/' docs/asciidoc/antora.yml | head -30

# Find files NOT using subs=attributes+ in code blocks
grep -rn "\[source," docs/ --include="*.adoc" | grep -v "subs=attributes" | head -10

PKI Reference Audit

# Find AD CS / HOME-CA references (should be marked deprecated)
grep -rn "HOME-ROOT-CA\|HOME-ISSUING-CA\|AD CS" docs/ --include="*.adoc"

# Verify Vault PKI is marked as primary
grep -rn "DOMUS-ROOT-CA\|DOMUS-ISSUING-CA\|Vault PKI" docs/ --include="*.adoc" | head -10

Infrastructure Inventory Audit

# List VMs mentioned in index.adoc
awk '/^\|.*10\.50\.1\./{print $1, $2, $3}' docs/asciidoc/modules/ROOT/pages/index.adoc

# Compare with infrastructure-inventory.adoc
awk '/^\|.*10\.50\.1\./{print $1, $2, $3}' docs/asciidoc/modules/ROOT/pages/architecture/infrastructure-inventory.adoc

# Find all IP references across docs
grep -roh "10\.50\.1\.[0-9]*" docs/ --include="*.adoc" | sort -t. -k4 -n | uniq -c | sort -rn | head -20

Navigation Audit

# List all runbook files
ls docs/asciidoc/modules/ROOT/pages/runbooks/*.adoc | xargs -I{} basename {} | sort

# List runbooks in nav.adoc
grep "runbooks/" docs/asciidoc/modules/ROOT/nav.adoc | awk -F'[/\\[\\]]' '{print $2}' | sort

# Find runbooks NOT in navigation (orphaned)
comm -23 \
  <(ls docs/asciidoc/modules/ROOT/pages/runbooks/*.adoc | xargs -I{} basename {} | sort) \
  <(grep "runbooks/" docs/asciidoc/modules/ROOT/nav.adoc | sed 's/.*runbooks\///' | sed 's/\[.*//' | sort) 2>/dev/null

Cross-Reference Audit

# Find cross-component xrefs (double colon)
grep -rn "xref:[a-z-]*::" docs/ --include="*.adoc" | head -10

# Find broken xrefs (files that don't exist)
for xref in $(grep -roh "xref:[^[]*" docs/ --include="*.adoc" | sed 's/xref://' | sort -u); do
  # Skip cross-component xrefs
  [[ "$xref" == *"::"* ]] && continue
  file="docs/asciidoc/modules/ROOT/pages/${xref}"
  [[ ! -f "$file" ]] && echo "MISSING: $xref"
done 2>/dev/null | head -10

Metadata Audit

# Check revdates across all pages
grep -rn "^:revdate:" docs/ --include="*.adoc" | awk -F: '{print $4, $1}' | sort | head -20

# Find pages without revdate
for f in docs/asciidoc/modules/ROOT/pages/**/*.adoc; do
  grep -q ":revdate:" "$f" || echo "NO REVDATE: $f"
done 2>/dev/null | head -10

# Check antora.yml revdate
grep "revdate:" docs/asciidoc/antora.yml

Status Audit

# Find all status indicators in projects/roadmaps
grep -rn ":status:" docs/asciidoc/modules/ROOT/pages/projects/ docs/asciidoc/modules/ROOT/pages/roadmaps/ 2>/dev/null

# Find "In Progress" items that may be stale
grep -rn "In Progress\|Pending\|TODO" docs/ --include="*.adoc" | grep -v template | head -20

Multi-Repo Audit

Run from ~/atelier/_bibliotheca/

# Check all domus-* repos for uncommitted changes
for repo in domus-*/; do
  status=$(git -C "$repo" status --short 2>/dev/null)
  [[ -n "$status" ]] && echo "=== $repo ===" && echo "$status"
done

# Check unpushed commits across all repos
for repo in domus-*/; do
  ahead=$(git -C "$repo" log --oneline origin/main..HEAD 2>/dev/null | wc -l)
  [[ $ahead -gt 0 ]] && echo "$repo: $ahead commits ahead"
done

# Find cross-component xref targets
for repo in domus-*/; do
  component=$(awk '/^name:/{print $2}' "$repo/docs/asciidoc/antora.yml" 2>/dev/null)
  [[ -n "$component" ]] && echo "$component → $repo"
done

Full Audit Script

Save as ~/.local/bin/domus-audit

#!/bin/bash
# Full documentation audit for domus-* repos

REPO="${1:-.}"
cd "$REPO" || exit 1

echo "=== DOCUMENTATION AUDIT: $(basename $(pwd)) ==="
echo ""

echo "## Runbook Count"
ls docs/asciidoc/modules/ROOT/pages/runbooks/*.adoc 2>/dev/null | wc -l

echo ""
echo "## Deprecated Hostname References (certmgr-01)"
grep -rn "certmgr-01" docs/ --include="*.adoc" 2>/dev/null | wc -l

echo ""
echo "## Hardcoded IPs (should be attributes)"
grep -rn "10\.50\.1\.[0-9]*" docs/ --include="*.adoc" 2>/dev/null | grep -v "antora.yml" | wc -l

echo ""
echo "## Orphaned Runbooks (not in nav)"
comm -23 \
  <(ls docs/asciidoc/modules/ROOT/pages/runbooks/*.adoc 2>/dev/null | xargs -I{} basename {} | sort) \
  <(grep "runbooks/" docs/asciidoc/modules/ROOT/nav.adoc 2>/dev/null | sed 's/.*runbooks\///' | sed 's/\[.*//' | sort)

echo ""
echo "## antora.yml revdate"
grep "revdate:" docs/asciidoc/antora.yml 2>/dev/null

echo ""
echo "## Stale Status Indicators"
grep -rn "In Progress" docs/asciidoc/modules/ROOT/pages/projects/ 2>/dev/null | wc -l

See Also