CR: Antora Documentation Ecosystem Audit

Change Summary

Change ID

CR-2026-03-25-antora-ecosystem-audit

Type

Documentation Quality / Technical Debt

Priority

P1 - High

Status

In Progress

Requested

2026-03-25

Owner

Evan Rosado

Background

Comprehensive audit of the Domus Digitalis Antora documentation ecosystem to identify issues, inconsistencies, and improvement opportunities across all hub and spoke repositories.

Scope

Repositories Audited

Repository Component Name Status

domus-docs

home (hub)

Audited

domus-infra-ops

infra-ops

Audited

domus-captures

captures

Audited

domus-ise-linux

ise-linux

Audited

domus-netapi-docs

netapi

Audited

domus-secrets-ops

secrets-infrastructure

Audited

domus-nvim

instrumentum

Audited

Additional Spokes (Confirmed Present)

  • domus-automation-ops

  • domus-gabriel-docs

  • domus-identity-ops

  • domus-ise-ops

  • domus-ise-windows

  • domus-linux-ops

  • domus-o11y-ops

  • domus-python

  • domus-siem-ops

  • domus-windows-ops

Critical Findings (P0)

1. Broken Include Paths in domus-infra-ops

Severity: BUILD BLOCKER

Issue: 8 pages reference include::_partials/attributes.adoc[] but the _partials/ directory does not exist. Should use include::partial$attributes.adoc[] (Antora syntax).

Affected Files:

docs/asciidoc/modules/ROOT/pages/
├── ad-cs-linux-certificate-template.adoc
├── ipsk-failover.adoc
├── ise-certificate-troubleshooting.adoc
├── vault-cert-deployment.adoc
├── byod-certificate-management.adoc
├── pki-strategy.adoc
├── domus-pki-ceremony.adoc
└── vault-troubleshooting.adoc

Fix: Replace include::_partials/ with include::partial$ or remove if no longer needed.

2. Zabbix Server Placeholder Attribute

Severity: DOCUMENTATION BROKEN

Repository: domus-ise-linux

Issue: antora.yml line 335 defines:

zabbix-server: <zabbix-server-ip>

This renders literally as <zabbix-server-ip> in documentation instead of an actual IP.

Affected File: modules/ROOT/pages/04-linux-client/monitoring.adoc (lines 77, 80, 134-135, 240, 258-259, 352, 355, 431)

Fix: Set actual Zabbix server IP or hostname in antora.yml.

3. Subnet Typo in Documentation

Severity: INCORRECT INFORMATION

Repository: domus-infra-ops

File: documentation-hub-setup.adoc line 46

Issue:

subnet-mgmt: 10.50.100.0/24  # WRONG

Should be:

subnet-mgmt: 10.50.1.0/24    # CORRECT

High Priority Findings (P1)

4. Hardcoded Infrastructure Values

Repository: domus-infra-ops

Count: 14 instances, 5 critical

Critical Files:

File Issue

vault-pki-quick-reference.adoc

Line 35: TARGET_IP="10.50.10.138" + inconsistent table (shows 10.50.10.122)

terraform-iac.adoc

Lines 4-5: k3s-master-02/03 IPs hardcoded (10.50.1.121, 10.50.1.122)

terraform-iac.adoc

Gateway/DNS hardcoded: 10.50.1.1, 10.50.1.90

network-infrastructure-discovery.adoc

DNS server IP hardcoded in dig command

Fix: Create missing attributes and use subs=attributes+ in code blocks.

5. pfSense to VyOS Migration Incomplete

Status: Migration completed 2026-03-07, documentation lagging

Repositories Affected:

  • domus-ise-linux - {pfsense-ip} still referenced

  • domus-infra-ops - Some runbooks reference pfSense

  • domus-captures - Case studies mention pfSense

Deprecated Attributes (remove by 2026-06):

pfsense-hostname: DEPRECATED → use vyos-vip
pfsense-ip: DEPRECATED → use vyos-vip

6. Missing k3s Cluster Attributes

Repository: domus-infra-ops

Issue: IPs defined but hostnames missing:

# Defined:
k3s-master-02-ip: 10.50.1.121
k3s-master-03-ip: 10.50.1.122

# Missing:
k3s-master-02-hostname: ???
k3s-master-03-hostname: ???

7. Hardcoded Values in domus-captures

Affected Files:

File Issue

INC-2026-02-14-ise-saml-restoration.adoc

11+ hardcoded URLs (keycloak-01, ise-01 FQDNs)

INC-2026-03-16-zfold7-termux-gopass-ssh.adoc

Device IP 10.50.10.110, MAC address, BYOD FQDN hardcoded

Recommended New Attributes:

byod-domain: byod.inside.domusdigitalis.dev
zfold7-mac: 9C:83:06:CE:89:46
zfold7-ip: 10.50.10.110
vlan-data: 10

Medium Priority Findings (P2)

8. domus-secrets-ops Severely Under-Attributed

Current State: 17 attributes (metadata only)

Reference Comparison:

Repository Attributes

domus-infra-ops

515

domus-ise-linux

391

domus-captures

112

domus-netapi-docs

126

domus-secrets-ops

17

Recommendation: Sync infrastructure attributes from domus-infra-ops or use cross-component includes.

9. Hub Playbook Inconsistencies

Repository: domus-docs

Issue Details Action

domus-gabriel-docs

Present in antora-playbook-ci.yml but NOT in antora-playbook.yml (production)

Add to production or remove from CI

domus-instrumentum

Commented out with note "Push to GitHub first"

Push repo to GitHub, enable in playbook

GitHub Actions workflow

deploy.yml has if: false - completely disabled

Delete or document why kept

10. domus-nvim Minimal Content

Current State:

  • 35 attributes (tool config only)

  • 13-line nav.adoc

  • Empty examples/ directory

  • Empty partials/ directory

Recommendation: Either populate with content or mark as "minimal documentation" component.

Repository Health Scorecard

Repository Attributes Nav Lines Partials Critical Issues Grade

domus-infra-ops

515

356

37

3

A-

domus-captures

112

962

16

Minor

B+

domus-ise-linux

391

65

Good

1

B+

domus-netapi-docs

126

203

Good

0

A

domus-secrets-ops

17

40

Minimal

Lacking

D

domus-nvim

35

13

Empty

Minimal

C

What’s Working Well

  1. domus-infra-ops is reference implementation - 515 attributes, 37 partials, single source of truth pattern

  2. Partials architecture adopted - domus-captures has 370 include references

  3. Deprecation tracking - Clear migration paths with removal dates (2026-06, 2026-07)

  4. Attribute naming consistency - {component-hostname}, {component-ip} pattern followed

Remediation Plan

Phase 1: Critical Fixes (P0)

# Task Est. Effort

1.1

Fix 8 broken _partials includes in domus-infra-ops

30 min

1.2

Set zabbix-server attribute to actual IP

5 min

1.3

Fix subnet typo in documentation-hub-setup.adoc

5 min

Phase 2: High Priority (P1)

# Task Est. Effort

2.1

Add missing k3s hostname attributes

10 min

2.2

Replace hardcoded IPs in vault-pki-quick-reference.adoc

20 min

2.3

Replace hardcoded IPs in terraform-iac.adoc

15 min

2.4

Complete pfSense→VyOS reference migration

1 hour

2.5

Extract hardcoded values in domus-captures case studies

30 min

Phase 3: Medium Priority (P2)

# Task Est. Effort

3.1

Sync attributes to domus-secrets-ops

1 hour

3.2

Resolve domus-gabriel-docs playbook inconsistency

15 min

3.3

Enable domus-instrumentum in production playbook

30 min

3.4

Clean up or delete disabled GitHub Actions workflow

10 min

Verification

After remediation:

# Build all spokes locally
cd ~/atelier/_bibliotheca/domus-docs
make build 2>&1 | grep -E "WARN|ERROR"

# Verify no undefined attributes
grep -r '{[a-z].*}' --include="*.adoc" | grep -v "subs=" | head -50

Related Documentation

Changelog

Date Author Change

2026-03-25

Evan Rosado

Initial audit completed, CR created