Draft
Conversation
|
🤖 Here's your preview: https://z4vwg-raaaa-aaaam-aiiga-cai.icp0.io |
…t instructions - Fetch all 86 Learn Hub articles via Zendesk API into .migration/learn-hub/ (57 in-scope under how-does-icp-work/, 29 out-of-scope; each with learn_hub_* frontmatter and migrated: false) - Add .docs-plan/learn-hub-navigation.md: article-to-target mapping for all 9 content batches with action types (new/expand/reference/skip) and per-batch cross-link replacement tables - Add .docs-plan/learn-hub-migration.md: 9-step agent workflow covering skill loading, staging file reading, per-action templates, sidebar config (no changes needed), verification step for protocol content, intra-batch linking rules, skip article policy, and final cleanup PR checklist with human review gate - Update .docs-plan/decisions.md with migration structural decisions - Update .docs-plan/migration-plan.md with 9 batch entries - Remove Learn Hub from AGENTS.md duplicate-content rule and link rule - Remove Learn Hub LinkCard from docs/index.mdx
## Summary - Moves `docs/concepts/chain-fusion.md` → `docs/concepts/chain-fusion/index.md` (unchanged content, updated relative links) - Adds 6 new conceptual sub-pages under `docs/concepts/chain-fusion/`: - `bitcoin.md` — Bitcoin adapter, Bitcoin canister API, Bitcoin checker canister (SDN list), ckBTC architecture and flows - `ethereum.md` — HTTPS outcalls + chain-key ECDSA integration, EVM RPC canister architecture, ckETH/ckERC20 - `solana.md` — SOL RPC canister, Ed25519 threshold signing, ckSOL - `dogecoin.md` — Dogecoin adapter + canister (Bitcoin fork, same architecture) - `exchange-rate-canister.md` — XRC on uzr34, request/response format, cycle costs, median rate logic - `chain-key-tokens.md` — Architecture (minter/ledger/index/archive), minting flows, redemption flows, deployed tokens table - Deletes all 10 staging files from `.migration/learn-hub/how-does-icp-work/chain-fusion/` - Updates cross-links in `chain-key-cryptography.md`, `concepts/index.md`, `choose-your-path.md`, and the four chain-fusion guide pages ## Sync recommendation `informed by learn hub staging files — chain-fusion section`
marc0olo
force-pushed
the
infra/learn-hub-migration-prep
branch
from
dabad66 to
d191270
Compare
## Summary - Creates `docs/concepts/protocol/` subdirectory with 7 new concept pages: protocol stack overview, peer-to-peer, consensus, message routing, execution, state synchronization, and performance - Migrates 6 Learn Hub articles from the "Blockchain Protocol" section and 1 from the "What is ICP?" section (performance); all Learn Hub links within these pages replaced with internal paths - Restores 5 portal diagrams across the protocol pages: `core_protocol_layers`, `consensus_orders_messages`, `block_maker`, `consensus_notarization`, `state-sync`; adds 2 performance screenshots from the Learn Hub - Performance page: metric values linked to timestamped IC Dashboard API calls, 12-city RTT matrix table, synthetic benchmark latency data - Converts Concepts sidebar from `autogenerate` to explicit `items` array to fix lowercase group labels and control ordering; moves Protocol Stack after architecture pages; adds Chain Fusion and Protocol Stack index slugs labeled "Overview" to avoid duplicate group/child labels - Updates `docs/concepts/index.md`: adds Protocol Stack to Architecture section - Updates `docs/concepts/network-overview.md`: trims consensus subsection (detail now in consensus.md), links to protocol stack overview ## Staging files deleted - `.migration/learn-hub/how-does-icp-work/blockchain-protocol/blockchain-protocol.md` → `docs/concepts/protocol/index.md` - `.migration/learn-hub/how-does-icp-work/blockchain-protocol/consensus.md` → `docs/concepts/protocol/consensus.md` - `.migration/learn-hub/how-does-icp-work/blockchain-protocol/peer-to-peer.md` → `docs/concepts/protocol/peer-to-peer.md` - `.migration/learn-hub/how-does-icp-work/blockchain-protocol/message-routing.md` → `docs/concepts/protocol/message-routing.md` - `.migration/learn-hub/how-does-icp-work/blockchain-protocol/execution-layer.md` → `docs/concepts/protocol/execution.md` - `.migration/learn-hub/how-does-icp-work/blockchain-protocol/state-synchronization.md` → `docs/concepts/protocol/state-synchronization.md` - `.migration/learn-hub/out-of-scope/what-is-icp/performance.md` → `docs/concepts/protocol/performance.md` ## Sync recommendation hand-written <!-- Upstream: informed by Learn Hub articles "Blockchain Protocol", "Consensus", "Peer to peer", "Message Routing", "Execution Layer", "State Synchronization", "Performance" (migrated, source retired) -->
## Summary - Creates `docs/concepts/node-infrastructure.md` with full migration of two Learn Hub articles: IC-OS overview (SetupOS, HostOS, GuestOS) and Trusted Execution Environments - TEE section covers: SEV-SNP memory encryption, VM launch measurements, attestation reports (including node-to-node and external attestation paths), sealing keys, disk partition layout table (A/B sets, which partitions are encrypted and why), traditional-vs-sealing-key encryption history, HKDF/LUKS key derivation, full 7-step GuestOS upgrade process with Upgrade VM and mutual attestation, and full emergency recovery section (manual rollback with NNS proposal steps + Recovery-GuestOS mechanism with upgrade-vs-recovery comparison table) - Adds 3 images from Learn Hub: TEE architecture overview (`tee-overview.jpg`), SEV-SNP attestation report diagram (`tee-attestation-report.svg`), SEV-SNP key derivation diagram (`tee-key-derivation.svg`) - Adds `concepts/node-infrastructure` to the explicit Concepts sidebar after `app-architecture` - Updates `docs/concepts/https-outcalls.md`: replaces the Learn Hub TEE link with the new internal path; removes a stale Learn Hub further-reading link for the skipped HTTPS Outcalls article ## Staging files deleted - `.migration/learn-hub/how-does-icp-work/node-infrastructure/overview.md` → `docs/concepts/node-infrastructure.md` - `.migration/learn-hub/how-does-icp-work/node-infrastructure/trusted-execution-environments.md` → `docs/concepts/node-infrastructure.md#trusted-execution-environments` ## Sync recommendation hand-written <!-- Upstream: informed by Learn Hub articles "Overview" (Node Infrastructure), "Trusted Execution Environments" (migrated, source retired) -->
## Summary - Creates `docs/concepts/edge-infrastructure.md` covering API boundary nodes, HTTP gateways, the HTTP Gateway Protocol request lifecycle, and asset certification (certified variables for query responses) - Adds edge infrastructure architecture diagram from Learn Hub (`edge-infrastructure.png`) - Adds IC dashboard link for current API boundary node count - Adds `edge-infrastructure` to the explicit Concepts sidebar after `node-infrastructure` - Updates `ic-http-gateway` library link to renamed repo (`dfinity/ic-http-gateway-protocol`) - Adds a "See also" link at the top of `docs/references/http-gateway-spec.md` - The HTTPS Outcalls staging file (skipped article) is left untouched ## Staging files deleted - `.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md` → `docs/concepts/edge-infrastructure.md` (intro section) - `.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md` → `docs/concepts/edge-infrastructure.md` - `.migration/learn-hub/how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md` → `docs/concepts/edge-infrastructure.md#http-gateway-protocol` - `.migration/learn-hub/how-does-icp-work/icp-and-the-internet/asset-certification.md` → `docs/concepts/edge-infrastructure.md#asset-certification` ## Sync recommendation hand-written <!-- Upstream: informed by Learn Hub articles "ICP and the Internet", "ICP Edge Infrastructure", "HTTP Gateway Protocol", "Asset Certification" (migrated, source retired) -->
## 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 <!-- Upstream: informed by Learn Hub articles "Evolution & Scaling" (34576974172692), "Fault Tolerance" (34210647901460), "Subnet Creation" (34209955782420), "Chain Evolution" (34210120121748) (migrated, source retired) -->
## Summary - Adds `docs/concepts/certified-data.md` — concept page explaining: the verification problem (compare to Bitcoin SPV / Ethereum light clients), how ICP's single root public key enables chain-wide certificate verification, the certified state tree mechanism, certified variables interface, and applications (certified assets, Internet Identity) - Expands `docs/concepts/chain-key-cryptography.md`: - Adds vetKeys to the "Why threshold cryptography matters" benefits list - Adds DKG research paper link (`eprint.iacr.org/2021/339`) to the DKG section - Expands NNS on first use in the Deployed keys section - Adds context on why threshold ECDSA is significantly harder than threshold BLS (asynchronous network requirement, robustness against 1/3 faulty nodes, protocol papers); notes that Schnorr/Ed25519 protocols are simplified variants with the same properties - Updates `docs/concepts/security.md` — adds link to `certified-data.md` where certified variables are first explained (cross-referencing the concept page from the security model page) - Updates `docs/guides/backends/certified-variables.md` — links to the new concept page for background - Deletes all 4 staging files from `.migration/learn-hub/.../chain-key-cryptography/` ## Completeness audit (staff technical writer sign-off) Source articles audited element-by-element via Zendesk API raw HTML: - **Certified Communication** (34214090576404): all content migrated — verification problem, single public key approach, certified variables (update/query pattern), 32-byte value + Merkle trees ✓. No images or tables in source. - **Chain-Key Cryptography** (34209486239252): all content migrated — 5-benefit numbered list (including vetKeys now added), DKG explanation, threshold signature schemes ✓. No images or tables in source. - **Chain-Key Signatures** (34209497587732): all content migrated — threshold ECDSA vs BLS difficulty, robustness/asynchronous network requirement, research paper links, Schnorr/EdDSA as simplified variants ✓. No images or tables in source. - **Subnet Keys and Subnet Signatures** (34209540682644): all content migrated — 4 subnet key uses (random beacon, XNet signing, client validation, randomness), threshold BLS properties, DKG paper link now added ✓. No images or tables in source. ## Cross-referencing - `security.md` now links to `certified-data.md` at the point where certified variables are introduced as the solution to query call integrity - `certified-variables.md` (guide) links to both `certified-data.md` (concept) and `security.md` (security implications) - `chain-key-cryptography.md` links to `certified-data.md` and `vetkeys.md` ## Sync recommendation `hand-written` <!-- Upstream: informed by Learn Hub articles "Certified Communication" (34214090576404), "Chain-Key Cryptography" (34209486239252), "Chain-Key Signatures" (34209497587732), "Subnet Keys and Subnet Signatures" (34209540682644) (migrated, source retired) -->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Prepares the repo to migrate all developer-relevant content from
learn.internetcomputer.orginto the docs site before Learn Hub is taken down. No new docs pages are created in this PR — it lays the infrastructure for 9 follow-on content PRs.This PR is a draft. All 9 batch content PRs target this branch (
infra/learn-hub-migration-prep) rather thanmain. The full migrated site can be previewed here before anything merges tomain. Once all batches and the final cleanup PR are merged into this branch, a maintainer rebases onmainand marks this PR ready..migration/learn-hub/as Markdown withlearn_hub_*frontmatter (migrated: false). 57 in-scope (underhow-does-icp-work/) and 29 out-of-scope (underout-of-scope/)..docs-plan/learn-hub-navigation.md): every in-scope article mapped to a target file, action type (new/expand/reference/skip), batch number, and per-batch cross-link replacement table. Three articles are explicitly markedskipwith reasons and kept for human review in the final cleanup PR..docs-plan/learn-hub-migration.md): 9-step workflow an agent follows for each batch PR — skill loading (technical-documentation+icp-brand-voiceonly, no icskills needed for concept pages), staging file reading, per-action page templates, sidebar notes (nosidebar.mjschanges needed), technical verification step for protocol-layer content, intra-batch linking rules, skip article policy, and a final cleanup checklist with a human review gate before the staging directory is deleted. Brand voice is called out as critical — Learn Hub articles routinely use banned jargon that must be cleaned up during migration.AGENTS.mdrule updates: removed "Learn Hub" from the "never duplicate external docs" list; updated the "link to old docs" rule to direct agents todocs/concepts/and.docs-plan/learn-hub-migration.mdinstead of Learn Hub.docs/index.mdx: removed the Learn Hub<LinkCard>from the External Resources section..docs-plan/decisions.md(2026-05-06 entry)..docs-plan/migration-plan.md.What comes next (not in this PR)
9 content PRs, one per batch, each targeting
infra/learn-hub-migration-prep. Batches 1–4 have no dependencies and can run in parallel. GitHub Issues for the 9 batches will be created after this PR is reviewed.Sync recommendation
hand-written