docs: add evolution & scaling concept page (Batch 4)

[marc0olo]

Summary

• Creates docs/concepts/evolution-scaling.md covering four topics from the Learn Hub:
  • Fault tolerance: CUP mechanism, epoch checkpoints, node recovery steps, subnet recovery via NNS proposal, NNS canister failures (lifeline/root/governance upgrade hierarchy), and NNS subnet failures (manual node provider recovery)
  • Subnet creation: horizontal scaling via XNet messaging, 4-step subnet creation process (node onboarding, NNS proposal, community vote, subnet genesis)
  • Chain evolution: NNS-governed protocol upgrades, registry versioning, epoch-boundary coordination, CUP handoff to new replica version, upgrade governance
• Adds 6 images from Learn Hub source articles: subnet diagram, NNS proposal flow, registry versioning, epoch boundary transition, CUP handoff, upgrade proposal
• Adds concepts/evolution-scaling to the sidebar (explicit Concepts items array)
• Updates docs/concepts/chain-key-cryptography.md: replaces Learn Hub chain-evolution link with internal path
• Updates docs/references/glossary.md: replaces Learn Hub fault-tolerance link with internal path

Completeness audit (staff technical writer sign-off)

Source articles audited element-by-element via Zendesk API raw HTML:

• Evolution & Scaling (34576974172692): overview article only — content absorbed into sections ✓
• Fault Tolerance (34210647901460): all sections migrated including NNS canister/subnet failure sections and video links in Further reading ✓
• Subnet Creation (34209955782420): all content migrated including 2 images ✓ (DFINITY etymology intro and vertical/horizontal scaling textbook intro appropriately omitted as non-technical)
• Chain Evolution (34210120121748): all content migrated including 4 images and additional resources (blog post, whitepaper, videos) ✓ (historical Ethereum/Bitcoin upgrade context appropriately omitted)

Sync recommendation

hand-written

[marc0olo]

Review notes

Two broken links need to be resolved before merge:

Broken links (blocking, dependency on #209): The "Further reading" section links to protocol/state-synchronization.md and protocol/index.md. Neither path exists on main until PR #209 merges. These will produce dead links or build failures.

Options:

• Remove both links and add them back after docs: add protocol stack concept pages (Batch 1) #209 merges
• Batch-merge after docs: add protocol stack concept pages (Batch 1) #209

No other issues: frontmatter complete, chain-key-cryptography.md and glossary.md cross-links correctly updated, <!-- Upstream: --> comment present, no banned patterns.

[marc0olo]

Two issues to fix in docs/concepts/evolution-scaling.md before merging:

1. Em-dashes in "Further reading" bullets (lines 74–76)

Em-dashes (—) are banned project-wide per AGENTS.md. All three bullets in the "Further reading" section use them. Replace each — with : .

2. Broken links in "Further reading" (lines 74–75)

protocol/index.md and protocol/state-synchronization.md are referenced but don't exist yet — they land in PR #209. Options:

• Remove the two links temporarily and restore them after docs: add protocol stack concept pages (Batch 1) #209 merges, or
• Batch-merge this PR after docs: add protocol stack concept pages (Batch 1) #209 so the targets exist at merge time.

Either way, npm run build will fail with broken-link errors until #209 is in.

[marc0olo]

Feedback addressed:

• Replaced em-dashes with colons in all Further reading bullets
• Removed the two broken links to protocol/index.md and protocol/state-synchronization.md (both pages land in PR docs: add protocol stack concept pages (Batch 1) #209 and don't exist yet on main). The links can be restored once docs: add protocol stack concept pages (Batch 1) #209 merges. The body text reference on line 12 was also de-linked for the same reason.

[marc0olo]

Feedback addressed:

• Registry desired vs actual state: Added note after CUP handoff steps — "The registry records the desired configuration, not the current running version. A subnet may continue running an older version until the CUP handoff completes. Nodes determine the actual current version by querying peers for the highest valid CUP."
• "Subnet blockchain" terminology: Removed from step 4 ("The nodes form the subnet and begin accepting messages") and from the image alt text on line 48
• Summary block precision: Updated to "The first block of each epoch is a summary block containing the configuration for both the current epoch and the next one. Nodes therefore know the upcoming version from the start of the current epoch, not at the last moment."
• 55-minute video: Intentionally omitted — a 55-minute video is impractical as a docs reference for this page. The 10-minute core protocol upgrades video covers the same material at an appropriate depth.
• Post-merge link restoration: Tracked. State synchronization and protocol stack links to be restored once docs: add protocol stack concept pages (Batch 1) #209 is fully in the base branch.