Gap analysis: articles on learn.internetcomptuter.org vs developer-docs `reference` and `concepts`

[raymondk]

Developer docs vs. Help Center articles — coverage gaps

Comparison between:

• Articles (Help Center, 86 articles): /Users/raymond/tmp/learn/articles/ — indexed in INDEX.md
• Dev docs:
  • /Users/raymond/dev/dfinity/developer-docs/docs/concepts/ (14 files)
  • /Users/raymond/dev/dfinity/developer-docs/docs/reference/ (17 files)

The articles are educational/conceptual; the dev docs are developer-facing concepts + spec references. About 27 articles (NNS dapp UI, wallet flows, network stats, vision/history) are end-user content and appropriately absent from dev docs — they are listed in the Out of scope section and are not gaps.

Summary

• Well covered: Cycles, HTTPS outcalls, randomness, timers, vetKeys, orthogonal persistence, chain-key cryptography (intro), chain fusion (intro). Dev docs are equal or better than articles.
• Partially covered: Canisters, governance (NNS), SNS basics, principals — dev docs cover the topic but the articles go deeper on architecture, mechanics, or rationale.
• Major gaps: The entire Blockchain Protocol section (consensus, P2P, message routing, execution layer, state sync), Node Infrastructure (TEEs, IC-OS), Edge Infrastructure (boundary nodes), Evolution & Scaling (fault tolerance, subnet creation, chain evolution), and several Chain Fusion sub-topics (Bitcoin architecture, EVM RPC, SOL RPC, Dogecoin, exchange rate canister, ckBTC, chain-key tokens internals) have no dev-doc equivalent.
• Reference vs. concept: The dev docs have strong reference/spec material (interface spec, candid spec, ICRC standards, management canister, execution errors) that has no article counterpart — that asymmetry is fine.

Major gaps (no dev-doc coverage)

Blockchain protocol layers

The five articles under articles/How does ICP work/Blockchain Protocol/ have essentially zero dev-doc counterpart. concepts/network-overview.md mentions consensus and message routing in passing but does not constitute coverage.

Topic	Article	Dev doc	Notes
Consensus protocol	Blockchain Protocol/consensus.md	—	Block making, notarization, finalization, random beacon, finality
Peer-to-peer	Blockchain Protocol/peer-to-peer.md	—	Abortable Broadcast, QUIC transport, registry integration
Message routing	Blockchain Protocol/message-routing.md	—	Induction, XNet streams, per-round/per-checkpoint state certification
Execution layer	Blockchain Protocol/execution-layer.md	—	Deterministic Time Slicing, instruction limits, checkpoint intervals
State synchronization	Blockchain Protocol/state-synchronization.md	—	Checkpoints, catch-up packages, chunked state sync
Blockchain protocol overview	Blockchain Protocol/blockchain-protocol.md	—	Layered model intro

Node infrastructure

Topic	Article	Dev doc	Notes
Trusted Execution Environments	Node Infrastructure/trusted-execution-environments.md	—	SEV-SNP, attestation, sealing keys, disk encryption
Node architecture / IC-OS	Node Infrastructure/overview.md	—	SetupOS / HostOS / GuestOS

Evolution & scaling

Topic	Article	Dev doc	Notes
Fault tolerance	Evolution & Scaling/fault-tolerance.md	—	Subnet failure modes and recovery
Subnet creation	Evolution & Scaling/subnet-creation.md	—	Governance-driven subnet creation flow
Chain evolution	Evolution & Scaling/chain-evolution.md	—	Forkless protocol upgrades via threshold crypto
Evolution & scaling overview	Evolution & Scaling/evolution-scaling.md	—	Horizontal scaling story

Edge infrastructure

Topic	Article	Dev doc	Notes
Edge infrastructure	ICP and the Internet/icp-edge-infrastructure.md	—	Boundary nodes, gateway, edge caching
HTTP gateway protocol (concept)	ICP and the Internet/http-gateway-protocol.md	reference/http-gateway-spec.md (spec only)	Reference is a normative spec; there is no conceptual guide
Asset certification	ICP and the Internet/asset-certification.md	—	Conceptual coverage of asset trees / response verification
ICP and the internet (overview)	ICP and the Internet/icp-and-the-internet.md	—	How ICP serves web content directly

Chain Fusion sub-topics

concepts/chain-fusion.md is a strong overview but only mentions most of these in a sentence or table.

Topic	Article	Dev doc	Notes
Bitcoin integration architecture	Chain Fusion/bitcoin-integration.md	—	Adapter, P2P, Bitcoin canister, UTXO/fee queries
Bitcoin checker canister	Chain Fusion/bitcoin-checker-canister.md	—	Dedicated article, no dev doc
Chain-key Bitcoin (ckBTC)	Chain Fusion/chain-key-bitcoin.md	—	ckBTC-specific mechanics
Chain-key tokens (mechanics)	Chain Fusion/chain-key-tokens.md	—	Backing model, mint/burn, 1:1 peg
EVM RPC canister	Chain Fusion/evm-rpc-canister.md	—	Provider queries, response handling, trust model
SOL RPC canister	Chain Fusion/sol-rpc-canister.md	—	Solana RPC canister design
Dogecoin integration	Chain Fusion/dogecoin-integration.md	—	Mentioned in a table only
Exchange rate canister	Chain Fusion/exchange-rate-canister.md	—	XDR oracle, cycle pricing
Ethereum integration architecture	Chain Fusion/ethereum-integration.md	partial	concepts/chain-fusion.md covers it but not at the article's depth

Chain-key cryptography deep dives

concepts/chain-key-cryptography.md covers the basics well; these two articles go deeper.

Topic	Article	Dev doc	Notes
Certified communication (theory)	Chain-Key Cryptography/certified-communication.md	brief	SPV/light-client comparison, 32-byte certification, Merkle trees
Subnet keys & subnet signatures	Chain-Key Cryptography/subnet-keys-and-subnet-signatures.md	—	NNS issuance, certificate chains
Chain-key signatures (deep)	Chain-Key Cryptography/chain-key-signatures.md	partial	Threshold signing internals beyond what dev docs cover

Tokens & ledgers

Topic	Article	Dev doc	Notes
How token ledgers work	Tokens & Governance/how-token-ledgers-work-on-the-internet-computer.md	—	Ledger architecture, accounts, sub-accounts
Cycles ledger (mechanics)	Canister Smart Contracts/cycles-ledger.md	one sentence in concepts/cycles.md	Transfer semantics, ledger interface
Tokenomics (NNS)	Tokens & Governance/tokenomics.md	thin	Supply schedule, reward curves
Tokenomics (SNS)	SNS - Service Nervous System/tokenomics.md	—	SNS-specific tokenomics
Tokens & governance overview	Tokens & Governance/tokens-governance.md	partial	Conceptual framing missing from dev docs

Governance deep dives

concepts/governance.md covers NNS/SNS at a high level but is thin on:

Topic	Article	Dev doc	Notes
Neurons' Fund	NNS .../neurons-fund-nf.md	—	Mechanism not in dev docs
Proposal topics & types	NNS .../proposal-topics-and-types.md	—	Full taxonomy missing
Neuron attributes (age/dissolve bonuses)	NNS .../neuron-attributes.md	partial	2× at 8y, 1.25× at 4y not stated in dev docs
Voting rewards (formula)	NNS .../voting-rewards.md	partial	Reward distribution detail
SNS framework & architecture	SNS .../framework-and-architecture.md	—	SNS-as-framework angle missing
SNS DAO settings	SNS .../dao-settings.md	—	Configuration parameters not documented
SNS launch process	SNS .../launch.md	—	Launch decentralization-swap mechanics
SNS rewards	SNS .../rewards.md	—	SNS-specific reward mechanics
SNS proposals	SNS .../proposals.md	—	Proposal flow specific to SNS
SNS neurons	SNS .../neurons.md	—	SNS neuron model

Partial gaps (covered but the articles add value)

These topics exist in the dev docs but the articles offer additional depth, rationale, or framing worth porting in.

• Canisters / computational model — concepts/canisters.md covers execution and memory model but assumes the reader already knows what a canister is. Articles Canister Smart Contracts/canister-smart-contracts.md and computational-model.md provide the conceptual intro and Wasm-execution model framing.
• Canister control & principals — concepts/canisters.md mentions principals; concepts/security.md mentions msg.caller; reference/glossary.md defines principal in two lines. The articles canister-control.md and what-is-a-principal.md provide a real explanation. The dev docs link out to the learn hub instead of covering this.
• Cycles — concepts/cycles.md is excellent on mechanics; the article version contextualizes the model (reverse-gas, why it exists). Add the "why" to the dev doc intro.
• HTTPS outcalls — Both sides cover this well; articles add rationale and the consensus-on-responses story in slightly more accessible language.
• NNS overview — concepts/governance.md covers neurons/proposals/voting at ~250 lines; the articles split this into 6+ documents with much more depth on each.

Out of scope (intentionally absent from dev docs)

These articles are end-user content and should not be added to dev docs. Listed for completeness so they are not flagged as gaps in future passes.

• Wallet & NNS-dapp flows (How can I use ICP/Governance/*, Tokens & wallets/*) — login, send/receive ICP, sub-accounts, ICRC import, neuron stake/configure/top-up/disburse, maturity disbursement, custody options, quill flows. ~16 articles.
• Network stats (How can I use ICP/Network stats/*) — cycle burn, network topology, tx/s. 3 articles.
• Dashboards — Internet Computer dashboard, community-built dashboards. 2 articles.
• Project framing (What is ICP/Overview/*) — what is ICP, the vision, history. 3 articles.
• Performance & decentralization narratives (What is ICP/Performance/*, Decentralization/*) — performance, performance comparison, "not all transactions are equal", decentralization, ICP subsystems. 5 articles.
• SNS inspection (user-facing) — How to Inspect an SNS and Its Dapp Canisters (developers would use programmatic APIs).

Suggested fix priorities

High — fill these before anything else; they are entire missing pillars:

1. Protocol stack section (consensus / P2P / message routing / execution / state sync) — likely 4-5 new files under concepts/ or one combined concepts/protocol-stack.md.
2. Node infrastructure (TEEs + IC-OS) — concepts/node-infrastructure.md.
3. Chain Fusion expansion — Bitcoin architecture, EVM RPC, exchange rate canister, ckBTC mechanics. Either expand concepts/chain-fusion.md or add reference/chain-fusion-integrations.md.
4. SNS framework — framework, DAO settings, launch flow. New section under concepts/ or a guides area.

Medium:
5. Expand concepts/governance.md with Neurons' Fund, proposal taxonomy, neuron-attribute bonuses, voting-reward formula.
6. Certified variables / certified communication conceptual guide (companion to the existing spec).
7. Edge infrastructure (concepts/edge-infrastructure.md).
8. Evolution & scaling — fault tolerance, subnet creation, forkless upgrades.

Lower:
9. Promote the principal/canister-control material into the dev docs proper instead of linking out.
10. Tokenomics + token ledger architecture write-up.
11. State sync / checkpoints / catch-up packages (protocol-level; may belong in reference rather than concepts).

[raymondk]

Action items: merge Learn Hub articles into the developer docs

Goal: take down learn.internetcomputer.org (the Help Center articles in /Users/raymond/tmp/learn/articles/) and migrate the relevant content into dfinity/developer-docs.

TL;DR strategy

• Most articles are explanations of how ICP works, so they belong in docs/concepts/.
• A few belong in docs/reference/ (taxonomies, fixed lists, formulas).
• About 27 articles are end-user content (wallet flows, NNS-dapp UI, network stats, dashboards, vision/history) that does not belong in developer docs. They need a different home or to be retired.
• Existing dev-doc pages link out to Learn Hub in 20+ places. Those links must be replaced with internal links (or inlined content) before the site comes down.
• The dev-docs repo has a strict authoring workflow (AGENTS.md, .docs-plan/). Each migration page needs proper frontmatter, an <!-- Upstream: --> comment, and structural changes recorded in .docs-plan/decisions.md.

Recommended sequencing: do structural prep + the link-replacement audit first so the rest can be done in parallel as topic batches. Take Learn Hub down only after every link in dev docs resolves internally.

---

Decisions to make before starting

These should be settled and recorded in .docs-plan/decisions.md:

• Subdirectories under concepts/? Concepts is currently flat (14 files). Adding ~25 more makes it unwieldy. Recommended: create concepts/protocol/, concepts/governance/, concepts/chain-fusion/, concepts/node-infrastructure/. Sidebar autogen handles nested directories automatically.
• Source pinning for the articles. Three options: (a) add dfinity/learn (or wherever the articles live) as a .sources/ submodule for traceability; (b) one-shot migration with a single <!-- Upstream: migrated from Learn Hub <date> --> marker on each page; (c) hand-written, no upstream marker. Option (a) is the most consistent with existing patterns; option (b) is fine if Learn Hub is being retired and the source repo stops getting updates.
• Disposition of ~27 end-user articles. See Out of scope below. Pick one home: NNS dapp's own help/docs, a slimmed-down user-help site that survives the takedown, or accept loss with redirects to the dapp UI.
• Update AGENTS.md? Three places reference Learn Hub: line 137 (Duplicate content that lives in external docs (..., Learn Hub)) and line 144 (Link to Learn Hub or explain inline for external content). Both must be updated once Learn Hub is gone.
• One mega-PR or batched PRs? Recommended: batched PRs by topic area (9 batches below). Each is independently reviewable and matches the existing branch pattern docs/<slug>.

---

Categorization map

How each top-level article group lands in the dev docs:

Article group	Dev docs target	Notes
How does ICP work / Blockchain Protocol (6 articles)	concepts/protocol/ (new subdir)	Consensus, P2P, message routing, execution, state sync, overview
How does ICP work / Node Infrastructure (2 articles)	concepts/node-infrastructure.md (single page) or new subdir	Small enough for one page
How does ICP work / Evolution & Scaling (4 articles)	concepts/evolution-scaling.md (single page)	Fault tolerance, subnet creation, chain evolution, overview
How does ICP work / ICP and the Internet (5 articles)	concepts/edge-infrastructure.md + expand existing reference/http-gateway-spec.md	Add a conceptual companion to the spec
How does ICP work / Chain Fusion (10 articles)	concepts/chain-fusion/ subdir + extend reference/protocol-canisters.md	Per-chain architecture pages; canister IDs/methods stay in reference
How does ICP work / Chain-Key Cryptography (4 articles)	Expand existing concepts/chain-key-cryptography.md + new concepts/certified-data.md	Most fits under existing page; certified communication warrants its own concept page
How does ICP work / Canister Smart Contracts (6 articles)	Expand concepts/canisters.md + concepts/cycles.md + new concepts/principals.md	Principals deserve their own page (heavily referenced from glossary, canisters, security)
How does ICP work / Tokens & Governance (3 articles)	Expand concepts/governance.md + new concepts/tokenomics.md + new concepts/token-ledgers.md	Tokenomics is currently a one-liner
How does ICP work / NNS (7 articles)	Expand concepts/governance.md + new reference/nns-mechanics.md	Concepts for explanations; reference for the proposal-type taxonomy and reward formulas
How does ICP work / SNS (9 articles, including 1 user-facing)	New concepts/sns-framework.md + new section in reference/	SNS-as-framework and architecture in concepts; DAO settings parameters in reference
How does ICP work / Introduction (1 article: "How does ICP work?")	Merge into concepts/index.md or drop	Likely redundant with the existing index
What is ICP / Overview (3 articles)	Out of scope (marketing)	Move to internetcomputer.org marketing site or retire
What is ICP / Performance (3 articles)	Out of scope (marketing)	Same as above
What is ICP / Decentralization (2 articles)	Out of scope (marketing)	Same as above
How can I use ICP / Governance (NNS dapp UI, 14 articles)	Out of scope (end user)	NNS dapp help site
How can I use ICP / Tokens & wallets (4 articles)	Out of scope (end user)	NNS dapp help / quill docs
How can I use ICP / Network stats (3 articles)	Out of scope (operational)	Internet Computer dashboard help

---

Phase 1: structural prep (do first, single PR)

Branch: infra/learn-hub-migration-prep

• Add a decision entry to .docs-plan/decisions.md with today's date covering: (a) subdirectory choice for concepts/, (b) source-pinning approach for articles, (c) the article-to-page mapping above.
• Add the article migration to .docs-plan/migration-plan.md with one row per new page.
• If pinning articles as a submodule, add .sources/learn-articles (or whatever repo) and update .sources/VERSIONS. Update the AGENTS.md submodule table.
• Update AGENTS.md:
  • Remove "Learn Hub" from the "Duplicate content that lives in external docs" list (line 137).
  • Update the "Link to Learn Hub or explain inline" rule (line 144) to drop the Learn Hub option once migration is complete.
  • Optional: add a rule that says any new content covering protocol layers, governance mechanics, etc. lives in dev docs (not external).
• Update docs/index.mdx: replace the LinkCard title="Learn Hub" (line 45) with a link to a new concepts overview, or remove it.
• Update sidebar config in sidebar.mjs only if introducing nested concepts subdirs requires explicit grouping (autogenerate handles this for free).

---

Phase 2: migrate content (9 batched PRs)

Each batch: one branch (docs/<slug>), one PR, frontmatter + <!-- Upstream: --> comment + sync recommendation per AGENTS.md rules. Em-dashes are banned in dev-docs prose, scrub during migration.

Batch 1: Protocol layers

Branch: docs/concepts-protocol-stack. Effort: large.

• Create docs/concepts/protocol/index.md (overview, layered stack)
• Create docs/concepts/protocol/consensus.md from articles/How does ICP work/Blockchain Protocol/consensus.md (block making, notarization, finalization, random beacon, finality)
• Create docs/concepts/protocol/peer-to-peer.md from peer-to-peer.md (Abortable Broadcast, QUIC, registry integration)
• Create docs/concepts/protocol/message-routing.md from message-routing.md (induction, XNet streams, state certification)
• Create docs/concepts/protocol/execution.md from execution-layer.md (DTS, instruction limits, checkpoint intervals)
• Create docs/concepts/protocol/state-synchronization.md from state-synchronization.md (checkpoints, catch-up packages)
• Update concepts/network-overview.md line ~48 to link to the new protocol pages instead of Learn Hub
• Update reference/glossary.md entries for peer-to-peer, message-routing, consensus (lines 169, 174, 175, 363, 486, 492, 497) to link internally

Batch 2: Node infrastructure

Branch: docs/concepts-node-infrastructure. Effort: medium.

• Create docs/concepts/node-infrastructure.md from articles/How does ICP work/Node Infrastructure/overview.md and trusted-execution-environments.md (SetupOS / HostOS / GuestOS, SEV-SNP, attestation, sealing keys, disk encryption)
• Update concepts/https-outcalls.md line 89 to link to the new TEE section instead of Learn Hub

Batch 3: Edge infrastructure

Branch: docs/concepts-edge-infrastructure. Effort: medium.

• Create docs/concepts/edge-infrastructure.md from articles/How does ICP work/ICP and the Internet/icp-edge-infrastructure.md, http-gateway-protocol.md, asset-certification.md, icp-and-the-internet.md (boundary nodes, gateway, certification verification)
• Cross-link from reference/http-gateway-spec.md (the spec is reference; the new page is the conceptual guide)

Batch 4: Evolution & scaling

Branch: docs/concepts-evolution-scaling. Effort: small to medium.

• Create docs/concepts/evolution-scaling.md from articles/How does ICP work/Evolution & Scaling/ (fault tolerance, subnet creation, chain evolution, horizontal scaling)
• Update concepts/chain-key-cryptography.md line 102 to link to the new chain-evolution section instead of Learn Hub
• Update reference/glossary.md line on fault tolerance to link internally

Batch 5: Chain Fusion deep dives

Branch: docs/concepts-chain-fusion-deep-dives. Effort: large.

• Create docs/concepts/chain-fusion/bitcoin-architecture.md from articles/.../Chain Fusion/bitcoin-integration.md, bitcoin-checker-canister.md, chain-key-bitcoin.md
• Create docs/concepts/chain-fusion/ethereum-architecture.md from ethereum-integration.md
• Create docs/concepts/chain-fusion/evm-rpc-canister.md from evm-rpc-canister.md (architecture, trust model)
• Create docs/concepts/chain-fusion/sol-rpc-canister.md from sol-rpc-canister.md
• Create docs/concepts/chain-fusion/dogecoin-architecture.md from dogecoin-integration.md
• Create docs/concepts/chain-fusion/exchange-rate-canister.md from exchange-rate-canister.md
• Create docs/concepts/chain-fusion/chain-key-tokens.md from chain-key-tokens.md (mint/burn, 1:1 peg)
• Move the existing top-level concepts/chain-fusion.md to concepts/chain-fusion/index.md
• Update guides/chain-fusion/bitcoin.mdx line 1181 (Learn Hub link) to point at the new bitcoin-architecture page
• Update guides/chain-fusion/dogecoin.md upstream comment (line 186)
• Update reference/protocol-canisters.md line 282 (SNS Learn Hub link is unrelated; covered in batch 7)

Batch 6: Cryptography deep dives

Branch: docs/concepts-cryptography-deep-dives. Effort: medium.

• Expand docs/concepts/chain-key-cryptography.md with content from articles/.../Chain-Key Cryptography/chain-key-signatures.md, subnet-keys-and-subnet-signatures.md
• Create docs/concepts/certified-data.md from articles/.../Chain-Key Cryptography/certified-communication.md (SPV/light-client comparison, 32-byte certification, Merkle trees) — companion to the existing certified-variables guide

Batch 7: Governance expansions (NNS + SNS)

Branch: docs/concepts-governance-deep-dives. Effort: large.

• Expand docs/concepts/governance.md with content from articles/.../NNS .../neurons-fund-nf.md (Neurons' Fund mechanism), neuron-attributes.md (age + dissolve-delay bonuses), voting-rewards.md (reward formula and decline curve)
• Create docs/reference/nns-proposal-types.md from proposal-topics-and-types.md (full taxonomy as reference)
• Create docs/concepts/sns-framework.md from articles/.../SNS .../sns-service-nervous-system.md, framework-and-architecture.md, launch.md, neurons.md, proposals.md, rewards.md (SNS-as-framework angle)
• Create docs/reference/sns-dao-settings.md from dao-settings.md (parameter reference, replaces the Learn Hub link in guides/governance/managing.md line 124)
• Update guides/governance/managing.md:
  • Line 124 (DAO settings link) to point at the new reference page
  • Line 620 (SNS Neurons + SNS Rewards links) to point at the new sns-framework page
• Update concepts/governance.md line 81 (tokenomics link) to point at the new tokenomics page (batch 8)
• Update reference/protocol-canisters.md line 282 to point at the new sns-framework page
• Update reference/glossary.md lines 264 and 419 (governance Learn Hub links)

Batch 8: Tokens & ledgers

Branch: docs/concepts-tokens-ledgers. Effort: medium.

• Create docs/concepts/tokenomics.md from articles/.../Tokens & Governance/tokenomics.md and articles/.../SNS .../tokenomics.md (supply schedule, reward curves, token distribution)
• Create docs/concepts/token-ledgers.md from how-token-ledgers-work-on-the-internet-computer.md (ledger architecture, accounts, sub-accounts)
• Expand docs/concepts/cycles.md with cycles-ledger mechanics from articles/.../Canister Smart Contracts/cycles-ledger.md (transfer semantics, ledger interface beyond the existing one-line mention)

Batch 9: Canister concept fillers

Branch: docs/concepts-canister-fillers. Effort: medium.

• Create docs/concepts/principals.md from articles/.../Canister Smart Contracts/what-is-a-principal.md and canister-control.md (principal types, controller permissions)
• Update concepts/canisters.md line 73 (principal Learn Hub link) to point at the new principals page
• Update reference/glossary.md "principal" entry to link internally
• Expand docs/concepts/canisters.md with content from articles/.../Canister Smart Contracts/canister-smart-contracts.md and computational-model.md (Wasm execution model framing, conceptual intro)

---

Phase 3: link sweep

Once batches 1 through 9 are merged, do a final sweep:

• grep -rn "learn.internetcomputer.org" /Users/raymond/dev/dfinity/developer-docs/docs/ should return zero hits. If anything remains, fix it.
• grep -rn "learn.internetcomputer.org" /Users/raymond/dev/dfinity/developer-docs/AGENTS.md should return zero hits.
• npm run build passes.
• Manual smoke test of every previously-Learn-Hub-linking page in npm run dev.

Known link locations to watch for (audit list as of today):

File	Line	Target	Replace with
docs/index.mdx	45	Learn Hub LinkCard	concepts overview or remove
docs/guides/chain-fusion/bitcoin.mdx	1181	Bitcoin integration	concepts/chain-fusion/bitcoin-architecture.md
docs/guides/chain-fusion/dogecoin.md	186 (upstream comment)	Dogecoin integration	drop the Learn Hub line, keep portal/examples
docs/concepts/chain-key-cryptography.md	102	Chain Evolution	concepts/evolution-scaling.md
docs/guides/governance/managing.md	124	DAO Settings	reference/sns-dao-settings.md
docs/guides/governance/managing.md	620	SNS Neurons + Rewards	concepts/sns-framework.md
docs/concepts/governance.md	81	ICP tokenomics overview	concepts/tokenomics.md
docs/concepts/network-overview.md	48	Learn Hub generic	concepts/protocol/index.md
docs/concepts/https-outcalls.md	89	TEE-enabled subnets	concepts/node-infrastructure.md#tees
docs/concepts/https-outcalls.md	114	HTTPS outcalls Learn Hub	drop or replace with internal further-reading
docs/concepts/canisters.md	73	Principal	concepts/principals.md
docs/reference/protocol-canisters.md	282	SNS	concepts/sns-framework.md
docs/reference/glossary.md	169, 174, 175	Fault tolerance, consensus, P2P	concepts/evolution-scaling.md, concepts/protocol/consensus.md, concepts/protocol/peer-to-peer.md
docs/reference/glossary.md	264, 419	Governance	concepts/governance.md
docs/reference/glossary.md	363	Message routing	concepts/protocol/message-routing.md
docs/reference/glossary.md	486, 492, 497	Peer-to-peer	concepts/protocol/peer-to-peer.md

---

Phase 4: take down Learn Hub

Only after Phase 3 verifies zero broken outbound links.

• Set up redirects from learn.internetcomputer.org/hc/en-us/articles/<id> to the corresponding new dev-docs page. The Help Center article IDs are stable URL components; build a mapping table.
• For end-user articles (out of scope below) without a dev-docs target, redirect to the chosen home (NNS dapp help, etc.) or to a "this article has moved" landing page.
• Update DNS / hosting to retire the site.
• Search the broader web for inbound references to learn.internetcomputer.org (Google site: query, GitHub code search) and post the redirect map to the team so external link rot is minimized.

---

Out of scope: end-user articles (not for dev docs)

These ~27 articles must not be migrated into dev docs. They need a different home before takedown.

NNS dapp wallet flows (14 articles, all under articles/How can I use ICP/Governance/):

• how-can-i-log-into-the-nns-dapp.md
• how-can-i-find-my-icp-token-accounts.md
• how-can-i-add-an-icp-sub-account.md
• how-can-i-receive-icp-tokens.md
• how-can-i-send-icp-tokens.md
• how-can-i-import-icrc-tokens.md
• how-can-i-stake-a-neuron.md
• how-can-i-configure-a-neuron.md
• how-can-i-top-up-a-neuron.md
• how-can-i-disburse-a-neuron.md
• how-can-i-disburse-maturity.md
• how-can-i-stake-and-auto-stake-maturity.md
• internet-computer-dashboard.md
• community-built-dashboards.md

Tokens & wallets / quill flows (4 articles, under articles/How can I use ICP/Tokens & wallets/):

• icp-custody-options.md
• how-do-i-set-up-an-air-gapped-wallet-with-quill.md
• how-do-i-transfer-tokens-with-quill.md
• how-can-i-stake-icp-with-quill.md

Network stats (3 articles, under articles/How can I use ICP/Network stats/):

• cycle-burn.md
• network-topology.md
• txs.md

Marketing / vision / history (under articles/What is ICP/):

• Overview/what-is-icp.md
• Overview/what-is-the-vision-behind-icp.md
• Overview/what-has-happened-so-far.md
• Performance/performance.md
• Performance/performance-comparison.md
• Performance/not-all-transactions-are-equal.md
• Decentralization/decentralization.md
• Decentralization/icp-subsystems.md

SNS user-facing:

• articles/How does ICP work/SNS - Service Nervous System/how-to-inspect-an-sns-and-its-dapp-canisters.md (developers use programmatic APIs, end users use the SNS aggregator UI)

Suggested dispositions:

Group	Possible homes
NNS dapp wallet flows + quill	NNS dapp's own in-app help, or a slimmed help.internetcomputer.org site, or fold into the NNS dapp repo
Network stats / dashboards	dashboard.internetcomputer.org in-app help, or a sidebar on the dashboard itself
Marketing / vision / history	internetcomputer.org marketing site (likely already covered there); these can probably be retired with a redirect to the marketing home
SNS inspection (user-facing)	SNS aggregator app help, or retired

Pick a home for each group before takedown. Each redirected article needs a target URL.

[marc0olo]

Status update: all major gaps covered in PR #208

All major gaps identified in this analysis are now addressed in the Learn Hub migration prep branch (PR #208), through 9 batch content PRs merged into infra/learn-hub-migration-prep.

Coverage by section

Blockchain protocol layers — all five articles now have dedicated pages under docs/concepts/protocol/ (#209):

• Consensus: consensus.md
• Peer-to-peer: peer-to-peer.md
• Message routing: message-routing.md
• Execution layer: execution.md
• State synchronization: state-synchronization.md
• Performance: performance.md

Node infrastructure (#210): docs/concepts/node-infrastructure.md — covers TEEs (SEV-SNP, attestation, sealing keys) and IC-OS (SetupOS / HostOS / GuestOS)

Evolution & scaling (#212): docs/concepts/evolution-scaling.md — fault tolerance, subnet creation, chain evolution

Edge infrastructure (#211): docs/concepts/edge-infrastructure.md — boundary nodes, HTTP gateway, asset certification

Chain Fusion sub-topics (#213): dedicated pages under docs/concepts/chain-fusion/ for Bitcoin integration (including Bitcoin checker canister), Ethereum/EVM RPC, Solana RPC, Dogecoin, exchange rate canister, chain-key tokens

Chain-key cryptography (#214): docs/concepts/chain-key-cryptography.md expanded — threshold BLS, threshold ECDSA/Schnorr, subnet keys, key derivation; certified communication theory in docs/concepts/certified-data.md

Tokens & ledgers (#215): docs/concepts/ledgers.md (ledger architecture), docs/concepts/cycles.md (cycles ledger mechanics with full API), docs/concepts/network-economics.md (NNS and SNS tokenomics)

Governance deep dives (#216):

• docs/concepts/governance.md — neuron attributes (dissolve delay bonus, age bonus), voting rewards formula, Neurons' Fund
• docs/concepts/sns-framework.md — SNS architecture, neurons, proposals (all topic names), voting rewards
• docs/references/nns-proposal-types.md — full NNS proposal taxonomy
• docs/references/sns-settings.md — all NervousSystemParameters fields

Partial gaps now filled (#217): docs/concepts/principals.md (standalone principals page), docs/concepts/canisters.md expanded with controllers, upgrade hooks, inter-canister messaging

Items intentionally not migrated

The three remaining staging files were evaluated and not migrated:

• introduction/how-does-icp-work.md — a navigation/table-of-contents article with no substantive content; the concepts section serves this purpose
• icp-and-the-internet/https-outcalls.md — fully covered by existing docs/concepts/https-outcalls.md
• sns/how-to-inspect-an-sns-and-its-dapp-canisters.md — source uses dfx throughout (banned); not in old portal docs either; tracked as future work in guides: SNS inspection guide — how to query a live SNS and its canisters #228

Once PR #208 merges to main, this issue can be closed.