docs: migrate Learn Hub 'How does ICP work?' content into developer docs#208
Merged
Conversation
marc0olo
force-pushed
the
infra/learn-hub-migration-prep
branch
from
dabad66 to
d191270
Compare
…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`
## 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) -->
## Summary - **New page**: \`docs/concepts/network-economics.md\` — ICP token uses (governance, cycles, node rewards, SNS swaps), voting rewards and maturity mechanism (10%→5% over 8 years), supply dynamics (inflation/deflation with diagram), SNS tokenomics configuration; node provider rewards exchange rate computation (CMC, 30-day moving average) - **New page**: \`docs/concepts/ledgers.md\` — ICP ledger (AccountIdentifier), ICRC ledgers (principal + subaccount), append-only transaction log, archive canisters, index canisters, fee models - **Expanded**: \`docs/concepts/cycles.md\` — added cycles ledger section (canister IDs, ICRC-1/2/3, deposit/withdraw/create_canister, 100M fee per block, architecture diagram); updated cycles ledger limitation note to give two clear patterns (top-up vs proxy canister); added interface spec link to system-canisters reference - **Expanded**: \`docs/guides/canister-management/cycles-management.mdx\` — added "Calling canisters that require cycles" section covering inter-canister \`Cycles.add\`/\`msg_cycles_add\` pattern and the proxy canister template for CLI/agent use cases - **Updated**: \`docs/concepts/governance.md\` — replaced external Learn Hub link with internal \`network-economics.md\` link - **Updated**: \`docs/concepts/index.md\` — added network-economics and ledgers entries; fixed chain-fusion link to subdirectory - **Updated**: \`sidebar.mjs\` — added concepts/network-economics and concepts/ledgers sidebar entries - **Images**: cycles ledger architecture diagram, ICP supply dynamics (deflation/inflation) diagram ## Sync recommendation \`network-economics.md\`: \`informed by learn-hub staging — tokens-governance/tokens-governance.md, tokens-governance/tokenomics.md, sns/tokenomics.md\` \`ledgers.md\`: \`informed by learn-hub staging — tokens-governance/how-token-ledgers-work-on-the-internet-computer.md\` \`cycles.md\` additions: \`informed by learn-hub staging — canister-smart-contracts/cycles.md, canister-smart-contracts/cycles-ledger.md\` \`cycles-management.mdx\` additions: \`informed by dfinity/icp-cli-templates proxy template, dfinity/proxy-canister\`
## Summary
- **Expanded**: \`docs/concepts/governance.md\` — added 5 new sections:
neuron hotkeys, following rules (thresholds, catch-all, periodic
confirmation), voting thresholds (absolute majority / 3% quorum),
maturity operations (disburse/stake/auto-stake + modulation formula),
voting rewards formula R(t), and the Neurons' Fund (with disabled status
note)
- **New reference**: \`docs/references/nns-proposal-types.md\` — all 11
NNS proposal topics and their proposal types with descriptions, derived
from the full Learn Hub staging article
- **New concept page**: \`docs/concepts/sns-framework.md\` — SNS
architecture (SNS-W, upgrade paths, SNS subnet), launch process (swap
mechanics, min/max thresholds, fallback), SNS neurons (public, flexible
permissions, configurable voting power), SNS proposals (critical vs
non-critical topics, built-in + custom proposals), configurable voting
rewards; includes SNS rewards graph image
- **New reference**: \`docs/references/sns-settings.md\` — full
\`NervousSystemParameters\` reference with types and descriptions for
all fields (renamed from \`sns-dao-settings.md\` to match the "SNS
Settings" title)
- **Updated**: \`docs/guides/governance/managing.md\` — replaced 2 Learn
Hub links with internal paths (\`references/sns-settings.md\` and
\`concepts/sns-framework.md#sns-neurons\`)
- **Updated**: \`sidebar.mjs\` — added \`concepts/sns-framework\`,
\`references/nns-proposal-types\`, \`references/sns-settings\`
- **Deleted**: 14 consumed Learn Hub staging files (7 from \`nns/\`, 7
from \`sns/\`)
## Staging files deleted
-
\`.migration/learn-hub/how-does-icp-work/nns/{overview,neurons,proposals,neuron-attributes,neurons-fund-nf,voting-rewards,proposal-topics-and-types}.md\`
-
\`.migration/learn-hub/how-does-icp-work/sns/{sns-service-nervous-system,framework-and-architecture,launch,neurons,proposals,rewards,dao-settings}.md\`
## Sync recommendation
\`governance.md\` additions: \`informed by Learn Hub articles
"Overview", "Neurons", "Proposals", "Neuron Attributes", "Neurons' Fund
(NF)", "Voting Rewards" (migrated, source retired)\`
\`nns-proposal-types.md\`: \`informed by Learn Hub article "Proposal
Topics and Types" (migrated, source retired)\`
\`sns-framework.md\`: \`informed by Learn Hub articles "SNS — Service
Nervous System", "Framework and Architecture", "Launch", "Neurons",
"Proposals", "Rewards" (migrated, source retired)\`
\`sns-settings.md\`: \`informed by Learn Hub article "DAO Settings"
(migrated, source retired)\`
## Summary
- **New page**: \`docs/concepts/principals.md\` — the five principal
classes and how caller identity works (self-authenticating IDs, canister
IDs, anonymous principal, management canister, derived IDs)
- **Expanded**: \`docs/concepts/canisters.md\` — added two sections:
- "Controllers" now includes the full control structure table
(centralized / multi-sig / SNS-governed / immutable) and immutability
verification
- "### Upgrade" now includes the 3-step upgrade hook sequence
(pre\_upgrade → install → post\_upgrade) and trap behavior
- "Inter-canister messaging and error handling" covers the actor model,
bidirectional request/reply, guaranteed reply, and trap/rollback
semantics
- **Fixed**: \`docs/concepts/canisters.md\` line 73 — replaced Learn Hub
principal link with internal \`principals.md\` link
- **Updated**: \`docs/concepts/index.md\` — added principals.md entry
under Architecture with accurate description
- **Updated**: \`docs/references/glossary.md\` — updated principal entry
to link to \`concepts/principals.md\`
- **Deleted**: 4 consumed Learn Hub staging files from
\`canister-smart-contracts/\`
## Content placement rationale
The "Canister Control" Learn Hub article was grouped with "What is a
Principal?" in Learn Hub navigation, but the content (controller table,
upgrade hooks) belongs with canisters under Diataxis. \`principals.md\`
is focused on identity only; \`canisters.md\` absorbs all canister
management content.
The "Computational Model" article is fully migrated into
\`canisters.md\` (actor model, bidirectional messaging, guaranteed
reply, trap/rollback in "Inter-canister messaging and error handling").
## Staging files deleted
-
\`.migration/learn-hub/how-does-icp-work/canister-smart-contracts/{what-is-a-principal,canister-control,canister-smart-contracts,computational-model}.md\`
## Sync recommendation
\`principals.md\`: \`informed by Learn Hub article "What is a
Principal?" (migrated, source retired)\`
\`canisters.md\` additions: \`informed by Learn Hub articles "Canister
Smart Contracts", "Computational Model", "Canister Control" (migrated,
source retired)\`
…grams (#229) Closes #223. ## Summary Adds all images and diagrams that were not carried over when PR #213 migrated the chain fusion concept pages. Every image was individually evaluated; three were skipped (see below). ### Raster images added (sourced from Learn Hub) - **`bitcoin.md`**: full-stack integration architecture (adapter + protocol layers + Bitcoin canister); ckBTC system architecture (minter, ledger, Bitcoin canister, checker canister with labeled data flows); Bitcoin checker canister OFAC screening flow - **`dogecoin.md`**: Dogecoin adapter + canister + protocol-stack architecture diagram - **`exchange-rate-canister.md`**: XRC data-flow diagram (forex providers + exchanges → XRC → requesting canister) ### PlantUML diagrams added (source-controlled, new) - **`bitcoin.md`**: Bitcoin canister API spending-flow sequence (`bitcoin_get_utxos` → `sign_with_ecdsa` per input → `bitcoin_send_transaction`) - **`ethereum.md`**: EVM RPC component architecture (Internet Computer | JSON-RPC Providers | Ethereum) — recreated instead of using the Learn Hub raster, which had "Web 2.0" as a zone label (banned term) - **`solana.md`**: SOL RPC component architecture (Internet Computer | JSON-RPC Providers | Solana) — same reason; also complements the existing call-flow sequence diagrams already in this file ### Skipped - **Ethereum marketing render** (`34575033443348`): promotional 3D rendering, not a technical diagram; inconsistent with the clean diagram style used elsewhere - **ckBTC retrieval sequence** (`44598026440340`): the flow it depicts is already expressed in the existing PlantUML in `bitcoin.md` - **SNS supply-demand chart** (`34146812547476`): generic economics textbook diagram with no ICP-specific content ## Sync recommendation `informed by Learn Hub articles "Bitcoin Integration", "Bitcoin Checker Canister", "Chain-Key Bitcoin", "Dogecoin Integration", "Exchange Rate Canister", "EVM RPC Canister", "SOL RPC Canister" (migrated, source retired)`
…lean up staging (#230) ## Summary **Concepts sidebar** restructured into 6 named groups (closes #225, addresses #226): - **Network** — overview, node infrastructure, edge infrastructure, evolution & scaling - **Protocol stack** — promoted to its own top-level group (was nested inside Network, violating the 3-level nesting rule); 7 pages - **Canisters & capabilities** — canisters, principals, app architecture, cycles, orthogonal persistence, timers, verifiable randomness, HTTPS outcalls - **Cryptography** — chain-key cryptography, certified data, VetKeys - **Chain Fusion** — own group (7 sub-pages), not nested under Cryptography - **Trust & governance** — governance (moved to first), SNS framework, network economics, ledgers, security model (moved to last) **Top-level order** (#225): Languages now appears before Developer Tools. **Sentence case applied throughout** — all explicit sidebar labels and frontmatter page titles (89 files) converted from title case to sentence case per brand voice guidelines. Proper nouns (Chain Fusion, VetKeys, Bitcoin, etc.) and abbreviations (ICP, SNS, HTTPS, etc.) preserved. One known exception: `languages/motoko/icp-features/view-queries.md` is a synced file; its fix belongs upstream. **References section** restructured from a flat 17-item list into 4 thematic groups: - **Development reference** — management canister, cycles costs, subnet types, execution errors - **Canister registry** — system canisters, protocol canisters, application canisters, chain-key token canister IDs - **Standards** — ICRC standards, digital asset standards - **Governance** — NNS proposal types, SNS settings - Candid, IC interface spec, HTTP gateway spec, Internet Identity spec remain ungrouped (avoid 4-level nesting with IC interface spec sub-group) **`concepts/index.md`** updated throughout: 6 sections matching the sidebar, sentence-case link text, 4 pages previously missing (node-infrastructure, edge-infrastructure, evolution-scaling, sns-framework) added. **Staging cleanup**: `.migration/` directory removed — all 57 in-scope Learn Hub articles have been migrated; Zendesk URLs and history preserved in git log. SNS inspection guide tracked in #228. ## Sync recommendation hand-written
…nking - Fix 3 remaining Learn Hub links in glossary.md and protocol-canisters.md replaced with internal anchors (governance.md#the-network-nervous-system, sns-framework.md) - Wire inbound links to concept pages that had zero non-concept inbound links: chain-key-tokens.md and exchange-rate-canister.md now linked from protocol-canisters.md intro and Next steps; exchange-rate-canister.md also linked from network-economics.md with #how-rates-are-computed anchor - Add IC Dashboard API cross-references with section anchors to governance.md, ledgers.md, and protocol-canisters.md Next steps (#222) - Add first-use link for "cycles" in canisters.md lifecycle section (#226)
- Add four missing glossary entries: ckBTC, ICRC, stable memory, vetKeys each with a direct concept-page or reference link - Remove generic Rust and Motoko code examples from system-canisters.md (guide content that belongs in canister-calls guides, Motoko example was also using the broken canister: import syntax); replace with a pointer to inter-canister-calls guide - Fix system-canisters.md Dashboard API link from external skills URL to internal ic-dashboard-api.md reference
- certification.md: link "HTTP gateways" and "boundary nodes" on first use to concepts/edge-infrastructure.md#http-gateways and #api-boundary-nodes - asset-canister.md: link "HTTP gateways" on first use to edge-infrastructure - glossary.md TEE entry: add link to node-infrastructure.md#trusted-execution-environments
marc0olo
force-pushed
the
infra/learn-hub-migration-prep
branch
from
943b8fb to
14976b6
Compare
- Remove dummy "Start here" row from the Choosing an architecture table; fold its content into a lead-in sentence so the table is pure questions - Fix asset canister link to point to #frontend-options instead of #the-default-two-canister-model (link text now matches destination) - Update @icp-sdk/core/agent links from root js.icp.build to the specific /core/latest/libs/agent path in app-architecture.md and network-overview.md
…th model - Link Compute, Storage, Frontend hosting, and Scheduled tasks cells to their respective concept/guide pages - Update Internet Identity cell from "(passkey-based)" to "(passkey or OAuth)*" and add footnote explaining that II preserves privacy across apps regardless of the auth method used to sign in
…x terminology - network-overview.md: both "certified variables" inline links now point to certified-data.md#certified-variables instead of the guide - app-architecture.md: "stable memory" inline link now points to orthogonal-persistence.md#stable-memory instead of the data-persistence guide - verifiable-randomness.md: rename heading and body from "deterministic consensus systems" to "deterministic consensus protocols" (precise distributed-systems term)
- concepts/index.md: "ICP token uses" → "ICP native asset uses", "ICP token ledgers work" → "ICP ledgers work" - guides/index.md: move orphaned AI Coding Agents bullet into new "## Tooling" section so every entry belongs to a group - references/index.md: add "## Governance" section with nns-proposal-types.md and sns-settings.md (previously unlisted); rename "## Other" → "## Terminology"
…ce, and guide - concepts/chain-fusion/exchange-rate-canister.md: refocus on pure explanation (what the XRC is, supported rate types, median aggregation); remove Candid types and cycle cost table (now in reference only) - references/protocol-canisters.md: complete the XRC Candid interface with all ExchangeRateError variants and ExchangeRateMetadata from xrc.did; remove misleading CLI example (CLI cannot attach cycles on mainnet); slim rate aggregation prose to a single link to concept page - guides/chain-fusion/exchange-rates.mdx: new guide covering Rust and Motoko implementations, scaled-integer response parsing, historical rate requests, error handling table, and proxy canister pattern for CLI testing - guides/index.md: update Chain Fusion description to mention exchange rates
The prerequisites section was Rust-only in a guide covering both languages. Fold the language-agnostic prerequisite into the intro sentence and move the Cargo.toml block into the Rust tab where it is needed in context.
This was referenced May 11, 2026
marc0olo
changed the title
Migration is complete (all 9 batches merged). Remove the agent instruction file and article-to-file navigation map, which were purpose-built for the 9-batch execution and have no further function. Update the AGENTS.md "Never" rule so it no longer references the deleted file and reflects that Learn Hub is now retired rather than in progress.
marc0olo
added a commit
that referenced
this pull request
May 11, 2026
…ion.md Aligns with wording convention established in PR #208 (SNS framework page), which avoids "DAO" in prose and uses "community-governed" constructions instead. - "Full decentralization using a DAO" heading -> "Full community governance" - "DAO evolves" link text -> "community governance evolves" - "building your own DAO" -> "building your own governance system" - "alternative to DAO control" -> "alternative to community governance" - "implement a DAO from scratch" -> "implement a custom governance canister" - "basic DAO example" link text -> "basic governance example" - "the DAO is controlled by itself" -> "the governance canister is controlled by itself"
marc0olo
added a commit
that referenced
this pull request
May 11, 2026
## Summary - **\"dapp\"/\"dapps\" → \"app\"/\"apps\"** across all 12 security guide files; repository names in URLs preserved (`nns-dapp`, `encrypted-notes-dapp`), link labels updated (`NNS app`, `encrypted notes`) - **\"smart contract(s)\" → \"canister(s)\"** in `decentralization.md`, including the section heading and the blockchains admonition note - **Em-dashes removed from `<!-- Upstream: -->` comments** in all 11 remaining files (`identity-and-access-management.mdx` was already fixed in a previous commit) - **Informal phrasing removed** in `data-integrity-and-authenticity.md`: \"we will club composite_query\" and \"best of both worlds\" - **Garbled sentence fixed** in `identity-and-access-management.mdx` (mobile II section): the original had a sentence fragment mid-paragraph from a copy-paste error - **\"DAO\" removed from prose** in `decentralization.md`; replaced with \"community governance\", \"governance framework\", and \"custom governance canister\" following the convention established in PR #208 - **\"decentralized governance system\" → \"governance framework\"** throughout `decentralization.md` - **`composite_query` description corrected** in `data-integrity-and-authenticity.md`: \"query call\" → \"query methods\" (composite_query is a method type, not a call type) - **\"off-chain\" → \"offchain\" / \"external\"** in `decentralization.md`; bare \"onchain\"/\"offchain\" category labels replaced with descriptive terms (\"external components\", \"hosted as canisters\") - **\"tamper-resistant\" → \"tamperproof\"** in `observability-and-monitoring.md` (one word, per brand guide) - **\"on-chain\" → \"stored in the canister\"** in `observability-and-monitoring.md` ## Sync recommendation `informed by dfinity/portal` — content is derived from the portal source but diverges intentionally for brand voice compliance; no sync back to portal is expected.
raymondk
approved these changes
May 11, 2026
marc0olo
added a commit
that referenced
this pull request
May 12, 2026
…ces (#239) ## Summary Closes #235. Post-merge cleanup for PR #204 after PR #208 landed. - **`canister-control.md`**: SNS link → `docs/concepts/governance.md#the-service-nervous-system`; tokenomics/voting-power link → `docs/concepts/governance.md#neurons`; removed "See also" wiki bullet (no internal equivalent for SNS verification trust or swap trust content) - **`canister-upgrades.md`**: Removed wiki "current limitations" bullet for `pre_upgrade` bugs (no internal equivalent) - **`data-storage.md`**: Removed wiki "current limitations" bullet for long running upgrades and deserializer memory (no internal equivalent) - **`inter-canister-calls.md`**: Removed two wiki "current limitations" bullets for untrustworthy canisters and call graph loops (no internal equivalent) - **`data-integrity-and-authenticity.md`**: Asset certification Learn Hub link → `docs/guides/frontends/certification.md` Note: the rebase of `docs/security-port` on `main` is deferred — will be done as a final step before that PR merges. ## Sync recommendation hand-written (link fixes only; no content changes)
marc0olo
added a commit
that referenced
this pull request
May 12, 2026
## Summary - **\"dapp\"/\"dapps\" → \"app\"/\"apps\"** across all 12 security guide files; repository names in URLs preserved (`nns-dapp`, `encrypted-notes-dapp`), link labels updated (`NNS app`, `encrypted notes`) - **\"smart contract(s)\" → \"canister(s)\"** in `decentralization.md`, including the section heading and the blockchains admonition note - **Em-dashes removed from `<!-- Upstream: -->` comments** in all 11 remaining files (`identity-and-access-management.mdx` was already fixed in a previous commit) - **Informal phrasing removed** in `data-integrity-and-authenticity.md`: \"we will club composite_query\" and \"best of both worlds\" - **Garbled sentence fixed** in `identity-and-access-management.mdx` (mobile II section): the original had a sentence fragment mid-paragraph from a copy-paste error - **\"DAO\" removed from prose** in `decentralization.md`; replaced with \"community governance\", \"governance framework\", and \"custom governance canister\" following the convention established in PR #208 - **\"decentralized governance system\" → \"governance framework\"** throughout `decentralization.md` - **`composite_query` description corrected** in `data-integrity-and-authenticity.md`: \"query call\" → \"query methods\" (composite_query is a method type, not a call type) - **\"off-chain\" → \"offchain\" / \"external\"** in `decentralization.md`; bare \"onchain\"/\"offchain\" category labels replaced with descriptive terms (\"external components\", \"hosted as canisters\") - **\"tamper-resistant\" → \"tamperproof\"** in `observability-and-monitoring.md` (one word, per brand guide) - **\"on-chain\" → \"stored in the canister\"** in `observability-and-monitoring.md` ## Sync recommendation `informed by dfinity/portal` — content is derived from the portal source but diverges intentionally for brand voice compliance; no sync back to portal is expected.
marc0olo
added a commit
that referenced
this pull request
May 12, 2026
…ces (#239) ## Summary Closes #235. Post-merge cleanup for PR #204 after PR #208 landed. - **`canister-control.md`**: SNS link → `docs/concepts/governance.md#the-service-nervous-system`; tokenomics/voting-power link → `docs/concepts/governance.md#neurons`; removed "See also" wiki bullet (no internal equivalent for SNS verification trust or swap trust content) - **`canister-upgrades.md`**: Removed wiki "current limitations" bullet for `pre_upgrade` bugs (no internal equivalent) - **`data-storage.md`**: Removed wiki "current limitations" bullet for long running upgrades and deserializer memory (no internal equivalent) - **`inter-canister-calls.md`**: Removed two wiki "current limitations" bullets for untrustworthy canisters and call graph loops (no internal equivalent) - **`data-integrity-and-authenticity.md`**: Asset certification Learn Hub link → `docs/guides/frontends/certification.md` Note: the rebase of `docs/security-port` on `main` is deferred — will be done as a final step before that PR merges. ## Sync recommendation hand-written (link fixes only; no content changes)
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
2 participants
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
Migrates all 57 developer-relevant articles from the Learn Hub "How does ICP work?" section into the developer docs, replacing Learn Hub as the canonical source for ICP protocol concepts before the site is retired.
This was executed as 9 content batch PRs plus a post-migration review pass, all merged into this staging branch before landing on
main:Batch 1 — Protocol stack (#209): Consensus, peer-to-peer, message routing, execution layer, state synchronization, and performance concept pages under
docs/concepts/protocol/.Batch 2 — Node infrastructure (#210):
docs/concepts/node-infrastructure.md— TEE (SEV-SNP) attestation, IC-OS layer model (SetupOS / HostOS / GuestOS), TEE key derivation and disk encryption.Batch 3 — Edge infrastructure (#211):
docs/concepts/edge-infrastructure.md— boundary nodes, HTTP gateway, edge caching.Batch 4 — Evolution and scaling (#212):
docs/concepts/evolution-scaling.md— horizontal scaling via subnet sharding, fault tolerance, governance-driven subnet creation, forkless protocol upgrades.Chain fusion deep dives (#213): Expanded
docs/concepts/chain-fusion/with dedicated pages for Bitcoin integration, ckBTC mechanics, Ethereum integration, EVM RPC, Solana RPC, Dogecoin integration, and Exchange Rate Canister. Architecture and flow diagrams migrated topublic/concepts/chain-fusion/.Cryptography deep dives (#214): Expanded
docs/concepts/chain-key-cryptography.mdanddocs/concepts/certified-data.mdwith subnet keys, threshold signing internals, and certified communication theory.Tokens, ledgers, and cycles (#215): Expanded
docs/concepts/ledgers.mdanddocs/concepts/cycles.mdwith ledger architecture, accounts, sub-accounts, cycles ledger transfer semantics, and NNS tokenomics.Governance deep dives (#216): Expanded
docs/concepts/governance.mdand addeddocs/concepts/sns-framework.md— NNS neuron attributes and bonuses, voting rewards formula, Neurons Fund, proposal taxonomy, SNS framework and architecture, DAO settings, launch flow, SNS neurons and rewards, and SNS proposals.Principals and canister model (#217): Expanded
docs/concepts/principals.mdanddocs/concepts/canisters.md— principal model, canister control, Wasm execution model, anddocs/concepts/app-architecture.md.Post-migration holistic review (#218, #226):
Migration infrastructure (initial prep commits):
.docs-plan/learn-hub-migration.md— agent workflow and authoring rules for 9-batch execution.docs-plan/learn-hub-navigation.md— per-article mapping (target file, action type, cross-link table)AGENTS.md / CLAUDE.md— Learn Hub removed from external-docs list; linking rule updatedsidebar.mjs— all new concept pages registeredCloses
referenceandconcepts#190 — Gap analysis: articles on learn.internetcomptuter.org vs developer-docsreferenceandconceptsSync recommendation
hand-written (all pages authored from Learn Hub source articles via Zendesk API; no upstream repo to sync from)