firefrost-operations-manual/docs/reference/cross-linking-guide.md

Cross-Linking Guide for Firefrost Operations Manual

Purpose: Improve navigation by linking related documents
Created: February 16, 2026
Part of: Push to 100/100 repository health rating

---

Why Cross-Linking Matters

Problem: Users must rely on DOCUMENT-INDEX to find related content
Solution: Documents directly link to related docs

Benefits:

• Faster navigation
• Discover related content naturally
• Reduce reliance on index
• Better context for readers

---

Standard Cross-Link Format

Add "Related Documents" section near end of document (before closing):

## Related Documents

- [Infrastructure Manifest](../core/infrastructure-manifest.md) - Server IPs and specs
- [UFW Rules Guide](../security/ufw-rules.md) - Firewall configuration
- [Deployment Checklist](deployment-checklist.md) - Pre-deployment steps

Format rules:

• Use relative paths from current document
• Include brief description (3-8 words) after hyphen
• Group by topic (infrastructure, security, deployment, etc.)
• List 3-7 most relevant docs (not exhaustive)

---

Priority Documents for Cross-Linking

High Priority (Do First)

• Deployment guides → infrastructure-manifest.md
• Security docs → related security procedures
• Task READMEs → deployment plans, prerequisites
• Standards docs → related standards

Medium Priority

• Planning docs → related planning docs
• Relationship docs → consultant profiles, photos
• Archive docs → what they replaced

Low Priority (Nice to have)

• Troubleshooting → related guides
• Reference docs → source documents

---

Implementation Strategy

Gradual approach:

1. Add cross-links when touching a document (opportunistic)
2. No need to update all docs immediately
3. Focus on high-traffic docs first
4. Document cross-links in commit messages

Example commit:

Add cross-links to frostwall-protocol README

Related Documents section added with links to:
- infrastructure-manifest.md
- command-center-security README
- ufw-rules.md

Improves navigation per Fresh Claude Review Priority #3.

---

Automated Cross-Link Suggestions (Future)

Potential automation:

• Script analyzes document content
• Suggests related docs based on keywords
• Generates cross-link template
• Human reviews and approves

Script idea:

python3 automation/suggest-cross-links.py docs/tasks/frostwall-protocol/README.md
# Output: Suggested related documents based on content analysis

---

Cross-Link Validation

Link checker (automation/check-links.py) validates cross-links:

• Ensures targets exist
• Detects broken links
• Reports outdated references

Run before committing:

python3 automation/check-links.py --verbose

---

Examples

Example 1: Task README

## Related Documents

**Task Documentation:**
- [Deployment Plan](deployment-plan.md) - Complete 6-phase build guide
- [Prerequisites](prerequisites.md) - Pre-deployment checklist
- [Task Documentation Standard](../../standards/task-documentation-standard.md) - Standard this follows

**Infrastructure:**
- [Infrastructure Manifest](../../core/infrastructure-manifest.md) - Server details
- [Architecture Decisions](../../reference/architecture-decisions.md) - Why we chose this approach

Example 2: Deployment Guide

## Related Documents

**Before Deployment:**
- [Prerequisites Checklist](prerequisites.md) - What you need first
- [Infrastructure Manifest](../core/infrastructure-manifest.md) - Server access details

**Related Deployments:**
- [Gitea Deployment](gitea.md) - Git server setup
- [NextCloud Deployment](nextcloud.md) - File storage setup

**Security:**
- [UFW Rules](../security/ufw-rules.md) - Firewall configuration
- [SSH Hardening](../security/ssh-hardening.md) - Secure access

Example 3: Standard Document

## Related Documents

**Other Standards:**
- [Task Documentation Standard](task-documentation-standard.md) - FFG-STD-002
- [Naming Conventions](naming-conventions.md) - File/directory naming (when created)

**Implementation Examples:**
- [Whitelist Manager Task](../tasks/whitelist-manager/) - First full implementation
- [Frostwall Protocol Task](../tasks/frostwall-protocol/) - Complex example

---

Maintenance

Ongoing:

• Add cross-links when creating new docs
• Update links when documents move
• Remove links to deprecated docs
• Run link checker weekly

Quarterly review:

• Identify orphaned documents (no incoming links)
• Add missing high-value cross-links
• Verify link descriptions are accurate

---

Fire + Frost + Foundation = Where Love Builds Legacy 💙🔥❄️