# 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):

```markdown
## 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:**
```bash
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:
```bash
python3 automation/check-links.py --verbose
```

---

## Examples

### Example 1: Task README

```markdown
## 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

```markdown
## 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

```markdown
## 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** 💙🔥❄️