Navigation

Navigation Architecture

The domus-captures navigation spans 14 sections in a governance hierarchy, distributed across 8 nav partials totaling approximately 1,064 lines. The hierarchy is not alphabetical — it reflects organizational priority from strategic to operational.

Governance Hierarchy

Position in the navigation communicates importance. The ordering is deliberate and governed by STD-010.

Position Section Purpose

1

Strategic Objectives

North-star goals that drive all other work

2

Standards

Governance documents — the rules everything else follows

3

Training

Training session records and skill-building exercises

4

Patterns

Field-observed patterns organized by Aristotelian taxonomy

5

Case Studies

Real incidents, changes, and deployments

6

Sessions

Claude Code collaboration logs

7

Chronicle

Chronological worklogs and daily captures

8

Knowledge Base

Reference material and research documents

9

Education

Certification tracks, languages, literature

10

Operations

Runbooks, monitoring, and operational procedures

11

Projects

All projects following STD-001 structure

12

Meta

Documentation about the documentation system

13

Templates

Document templates for each file prefix

14

Drafts

Work in progress not yet assigned to a section

Nav Partials

The root nav.adoc includes 8 extracted partials. STD-009 requires any nav section exceeding 50 lines to be extracted.

File Lines Content

nav/standards.adoc

~60

STD-001 through STD-020 entries

nav/training-sessions.adoc

~40

Training session cross-references

nav/pattern-journal.adoc

~120

18-domain pattern taxonomy

nav/case-studies.adoc

~150

TAC, INC, CR, RCA, DEPLOY entries

nav/knowledge-base.adoc

~80

Reference documents and research

nav/education.adoc

~100

RHCSA, literature, languages, certifications

nav/chronicle-2026.adoc

~400

Monthly worklog listings for 2026

nav/chronicle-2025.adoc

~80

Monthly worklog listings for 2025

The main nav.adoc contains the top-level structure and inline sections that remain under 50 lines (Strategic Objectives, Sessions, Operations, Projects, Meta, Templates, Drafts).

Extraction Rule

STD-009 defines the extraction threshold:

Nav sections exceeding 50 lines MUST be extracted to partials/nav/<section>.adoc and included via include::partial$nav/<section>.adoc[].

This rule exists to keep nav.adoc scannable. A developer reading the root nav file sees the governance hierarchy at a glance without scrolling through hundreds of xref entries.

Adding New Sections

Process for adding a new nav section:

  1. Create the partial in partials/nav/<section-name>.adoc

  2. Add the include::partial$nav/<section-name>.adoc[] directive to nav.adoc at the correct governance position

  3. Maintain the hierarchy ordering — new sections slot into the existing sequence based on their organizational role, not alphabetically

  4. If the section is under 50 lines, it MAY remain inline in nav.adoc

  5. Run make and verify no build warnings related to navigation

Adding entries to an existing section requires only editing the relevant nav partial.

Cross-References

Two syntaxes govern cross-references, and confusing them causes broken links.

Same-component (single colon) — for links within domus-captures:

xref:education/rhcsa/index.adoc[RHCSA Study Track]
xref:codex/awk-field-extraction.adoc[awk Field Extraction]
xref:case-studies/incidents/INC-2026-03-16-001.adoc[Incident Report]

Cross-component (double colon) — for links to other spoke repositories:

xref:infra-ops::runbooks/vyos-deployment.adoc[VyOS Deployment Runbook]
xref:ise-linux::02-pki/certificate-enrollment.adoc[Certificate Enrollment]
xref:netapi::cli/ise/backup.adoc[ISE Backup CLI]
xref:secrets-ops::vault/ssh-certificates.adoc[SSH Certificates]

Always use full paths from the pages/ root. Relative xrefs fail in nested directory structures — this is a known Antora behavior documented in the project’s Known Issues.