docs: migrate Learn Hub 'How does ICP work?' content into developer docs

.docs-plan/decisions.md

@@ -4,6 +4,34 @@ Record decisions that constrain future work — things an agent needs to know th
 
 ---
 
+## 2026-05-06: Learn Hub migration — structure, staging, and sequencing
+
+**Context:** `learn.internetcomputer.org` (a Zendesk Help Center with ~86 articles) is being retired. Developer-relevant content must move into this docs site before the site goes down. Issues #187 and #190 document the full gap analysis. About 27 articles are end-user content (NNS dapp UI, wallet flows, network stats, vision/history) and are explicitly out of scope for developer docs.
+
+**Decision:**
+
+1. **`concepts/` subdirectory structure.** The flat 14-file layout cannot absorb ~20 additional pages cleanly. Add two subdirectories:
+   - `docs/concepts/protocol/` — six protocol-layer pages (consensus, P2P, message routing, execution, state sync, overview)
+   - `docs/concepts/chain-fusion/` — per-chain architecture pages; the existing `concepts/chain-fusion.md` moves to `concepts/chain-fusion/index.md`
+   - All other new pages stay flat under `docs/concepts/` (node-infrastructure, edge-infrastructure, evolution-scaling, certified-data, principals, tokenomics, token-ledgers, sns-framework)
+
+2. **Source staging.** All Learn Hub articles are committed as raw Markdown into `.migration/learn-hub/`, preserving the original category/section folder structure, before any content PRs are opened. Each batch PR reads from the staging files, writes proper docs pages, and deletes the staging files in the same commit. When `.migration/learn-hub/` is empty, the directory is removed and the migration is done. Each migrated page uses `<!-- Upstream: informed by Learn Hub article "<title>" (migrated, source retired) -->` — no ongoing sync relationship. PR sync recommendation: `hand-written`.
+
+3. **End-user articles are out of scope.** All articles under "What is ICP?" (marketing/vision), "How can I use ICP? / Governance" (NNS dapp UI flows), "How can I use ICP? / Tokens & wallets" (quill/wallet how-tos), and "How can I use ICP? / Network stats" are not migrated into developer docs. Their disposition (NNS dapp help, IC dashboard help, marketing site) is handled outside this repo.
+
+4. **Batched PRs.** One `infra/learn-hub-migration-prep` PR does structural setup (staging files, decisions, navigation map, sidebar config, CLAUDE.md rule updates). Then 9 content PRs (`docs/<slug>`) migrate topic batches. See `.docs-plan/learn-hub-navigation.md` for the full batch-to-file mapping.
+
+5. **CLAUDE.md rule retirement.** Two rules reference Learn Hub and must be updated once all batch PRs are merged:
+   - The "never duplicate Learn Hub" line in the "Never" section must drop the Learn Hub reference.
+   - The "link to Learn Hub or explain inline" line in the "Never link to old docs" decision (2026-03-13 below) must be replaced with an instruction to link internally.
+   After the final batch PR merges, open a follow-up `infra/` PR to make these two edits.
+
+**Rationale:** Staging files in `.migration/learn-hub/` give every agent a stable, repo-local source to read before writing — consistent with the `.sources/` discipline for all other upstream content. Deleting staging files in the same PR as the content write makes progress unambiguous and prevents the staging directory from drifting out of sync. Subdirectories in `concepts/` are needed for the sidebar to remain navigable; two subdirs (not five) keeps the nesting shallow.
+
+**When to revisit:** Once `.migration/learn-hub/` is deleted in the final content PR, update this entry to "fully reflected in codebase" and remove it.
+
+---
+
 ## 2026-04-27: CLI and language tabs are always separate
 
 **Context:** Some pages were mixing CLI commands into the same `<Tabs syncKey="lang">` group as Motoko and Rust code. Other pages (e.g. `cycles-management.mdx`, `lifecycle.mdx`) kept CLI as standalone blocks with language tabs appearing separately. The mixed approach creates an awkward tab for users who just want a quick CLI command.

.docs-plan/migration-plan.md

@@ -397,3 +397,23 @@ languages/rust/index.md
 - **All icp-cli commands, flags, and installation instructions must be verified** against the icp-cli repo source (`dfinity/icp-cli`, `docs/reference/cli.md`). Never guess CLI syntax — fetch with: `gh api repos/dfinity/icp-cli/contents/docs/reference/cli.md --jq '.content' | base64 -d`
 - Each stub page contains `<!-- Content Brief -->`, `<!-- Source Material -->`, and `<!-- Cross-Links -->` HTML comments — read these before writing.
 - After completing a page, open a PR with a `## Sync recommendation` section and link it to the corresponding GitHub Issue.
+
+---
+
+## Learn Hub migration batches
+
+Nine content PRs to migrate learn.internetcomputer.org articles into `docs/`. Source staging files are in `.migration/learn-hub/`. Full article-to-file mapping and cross-link instructions: `.docs-plan/learn-hub-navigation.md`. Per-batch agent workflow: `.docs-plan/learn-hub-migration.md`.
+
+To claim a batch: check `git ls-remote origin docs/concepts-*` — branch exists means claimed, open PR against `infra/learn-hub-migration-prep` means in progress, branch gone (merged) means done. No GitHub Issues needed. Full workflow: `.docs-plan/learn-hub-migration.md`.
+
+| Batch | Branch | Target files | Effort | Status |
+|---|---|---|---|---|
+| 1 — Protocol stack | `docs/concepts-protocol-stack` | `concepts/protocol/index.md`, `consensus.md`, `peer-to-peer.md`, `message-routing.md`, `execution.md`, `state-synchronization.md` | Large | open |
+| 2 — Node infrastructure | `docs/concepts-node-infrastructure` | `concepts/node-infrastructure.md` | Medium | open |
+| 3 — Edge infrastructure | `docs/concepts-edge-infrastructure` | `concepts/edge-infrastructure.md` | Medium | open |
+| 4 — Evolution & scaling | `docs/concepts-evolution-scaling` | `concepts/evolution-scaling.md` | Small–medium | open |
+| 5 — Chain Fusion deep dives | `docs/concepts-chain-fusion-deep-dives` | `concepts/chain-fusion/index.md` (moved), `bitcoin.md`, `ethereum.md`, `solana.md`, `dogecoin.md`, `exchange-rate-canister.md`, `chain-key-tokens.md` | Large | open |
+| 6 — Cryptography deep dives | `docs/concepts-cryptography-deep-dives` | `concepts/certified-data.md`, expand `concepts/chain-key-cryptography.md` | Medium | open |
+| 7 — Governance deep dives | `docs/concepts-governance-deep-dives` | expand `concepts/governance.md`, `concepts/sns-framework.md`, `references/nns-proposal-types.md`, `references/sns-dao-settings.md` | Large | open (do batch 8 first) |
+| 8 — Tokens & ledgers | `docs/concepts-tokens-ledgers` | `concepts/tokenomics.md`, `concepts/token-ledgers.md`, expand `concepts/cycles.md` | Medium | open |
+| 9 — Canister concept fillers | `docs/concepts-canister-fillers` | `concepts/principals.md`, expand `concepts/canisters.md` | Medium | open |

AGENTS.md

@@ -134,14 +134,14 @@ git checkout main
 - Reference `dfx` — it is deprecated and banned
 - Use `mo:base` imports in Motoko code examples — use `mo:core` instead. Critical replacements: `Buffer` → `List`, `HashMap`/`TrieMap`/`Trie`/`RBTree` → `Map`, `Deque` → `Queue`, `OrderedMap` → `pure/Map`, `OrderedSet` → `pure/Set`
 - Create `.mdx` files without a clear need for interactive components — default to `.md`
-- Duplicate content that lives in external docs (icp-cli, JS SDK, icskills, Learn Hub)
+- Duplicate content that lives in external docs (icp-cli, JS SDK, icskills)
 - Edit synced files directly (`docs/languages/motoko/`, `docs/guides/tools/migrating-from-dfx.md`)
 - Nest sidebar items more than 3 levels deep
 - Skip reading source material before writing a page
 - Write code snippets from memory — find and adapt from actual upstream code in `.sources/`
 - Modify the rationale or context of existing decisions in `.docs-plan/decisions.md` — you may remove entries that are fully reflected in the current codebase but never alter reasoning behind active decisions
 - Add `Co-Authored-By` or any AI attribution to commits or PR descriptions
-- Link to `internetcomputer.org/docs/` — that site is retired. For internal pages use relative paths, not absolute `docs.internetcomputer.org/...` URLs. Link to Learn Hub or explain inline for external content.
+- Link to `internetcomputer.org/docs/` — that site is retired. For internal pages use relative paths, not absolute `docs.internetcomputer.org/...` URLs. Explain inline or link to `docs/concepts/` for protocol-level background; do not link to `learn.internetcomputer.org` (Learn Hub has been retired; its content is now in this site under `docs/concepts/`).
 - Link to internal pages that don't exist — every `[text](path.md)` must resolve to an actual file. Run `ls <target>` before linking. Links to `.mdx` pages use `.md` extension (Astro resolves both).
 - Link to a page without a section anchor when the surrounding context refers to a specific topic covered by a subsection — always check the target file's headings and include `#anchor` when a more precise destination exists. Verify anchors by grepping headings: `grep "^## \|^### " <target>`. Anchor slugs: lowercase, spaces → `-`, special chars stripped.
 - Link to `https://cli.internetcomputer.org/` (bare root) — all CLI doc pages are under a versioned path. Use `https://cli.internetcomputer.org/0.2/<path>` (current slug; verify with `cat .sources/icp-cli/docs-site/versions.json`) and confirm the path exists in `.sources/icp-cli/docs/<path>.md`. For command-specific links add a section anchor from `.sources/icp-cli/docs/reference/cli.md` (e.g. `#icp-canister-logs`, `#icp-canister-settings-update`, `#icp-cycles`). When bumping icp-cli to a new minor version, follow the "Link adaptation for `icp-cli`" checklist in "Bumping submodules".

docs/concepts/app-architecture.md

@@ -1,5 +1,5 @@
 ---
-title: "Application Architecture"
+title: "Application architecture"
 description: "How ICP applications are structured: canisters, frontends, and inter-canister communication"
 sidebar:
   order: 3
@@ -28,14 +28,16 @@ This flow replaces the traditional web stack. There is no separate web server, a
 
 | Concern | Traditional web app | ICP application |
 |---------|-------------------|-----------------|
-| **Compute** | Application server (Node, Django, etc.) | Backend canister (Wasm) |
-| **Storage** | Database (Postgres, MongoDB, etc.) | Canister stable memory (up to 500 GiB) |
-| **Frontend hosting** | CDN + static file server | Asset canister |
-| **Authentication** | OAuth provider or custom auth | [Internet Identity](../guides/authentication/internet-identity.md) (passkey-based) |
-| **Scheduled tasks** | Cron jobs, worker queues | Canister timers |
+| **Compute** | Application server (Node, Django, etc.) | [Backend canister](canisters.md) (Wasm) |
+| **Storage** | Database (Postgres, MongoDB, etc.) | [Canister stable memory](orthogonal-persistence.md) (up to 500 GiB) |
+| **Frontend hosting** | CDN + static file server | [Asset canister](../guides/frontends/asset-canister.md) |
+| **Authentication** | OAuth provider or custom auth | [Internet Identity](../guides/authentication/internet-identity.md) (passkey or OAuth)\* |
+| **Scheduled tasks** | Cron jobs, worker queues | [Canister timers](timers.md) |
 | **External API calls** | Server-side HTTP requests | [HTTPS outcalls](https-outcalls.md) |
 | **Infrastructure management** | You manage servers, scaling, uptime | The network handles replication and availability |
 
+\* With Internet Identity, users authenticate using a passkey or an OAuth provider (Google, Apple, etc.). Either way, each app receives a unique, app-specific principal: your canister never sees the OAuth credential or any cross-app identifier. This gives stronger privacy guarantees than traditional OAuth flows.
+
 The key difference: ICP applications are self-contained. You deploy code and data to canisters, and the network provides compute, storage, and serving. There is no infrastructure to provision or maintain.
 
 ## Architectural patterns
@@ -71,7 +73,7 @@ For maximum throughput, distribute canisters across multiple [subnets](network-o
 
 ## Data storage
 
-Canisters store data in heap memory during execution and can persist data across upgrades using [stable memory](../guides/backends/data-persistence.md#store-data-durably): there is no external database. Libraries provide familiar data-structure abstractions on top of raw stable memory:
+Canisters store data in heap memory during execution and can persist data across upgrades using [stable memory](orthogonal-persistence.md#stable-memory): there is no external database. Libraries provide familiar data-structure abstractions on top of raw stable memory:
 
 - **Motoko:** the [`core` standard library](https://mops.one/core/docs) includes persistent data structures designed for upgrade-safe storage.
 - **Rust:** [`ic-stable-structures`](https://docs.rs/ic-stable-structures/latest/ic_stable_structures/) provides `StableBTreeMap` and other structures for stable memory.
@@ -84,15 +86,16 @@ Not every ICP application needs the default asset canister. Your options:
 
 - **Asset canister**: the standard approach. Deploy your built frontend (React, Svelte, vanilla JS, etc.) to an asset canister that serves it over HTTP. See [Asset canister](../guides/frontends/asset-canister.md).
 - **Framework-specific canister**: use a framework like Juno that provides a more opinionated hosting solution on ICP.
-- **Offchain frontend**: host your frontend on traditional infrastructure (Vercel, Netlify, etc.) and call ICP canisters from JavaScript using [`@icp-sdk/core/agent`](https://js.icp.build). Useful during migration or when you need features that asset canisters don't support.
+- **Offchain frontend**: host your frontend on traditional infrastructure (Vercel, Netlify, etc.) and call ICP canisters from JavaScript using [`@icp-sdk/core/agent`](https://js.icp.build/core/latest/libs/agent). Useful during migration or when you need features that asset canisters don't support.
 - **No frontend**: backend-only canisters that expose a Candid API for other canisters or CLI tools to call.
 
 ## Choosing an architecture
 
+Start with a [single canister](#single-canister): it is the right choice for most applications. Work through these questions only if your needs grow:
+
 | Question | If yes | If no |
 |----------|--------|-------|
-| Start here | [Single canister](#single-canister): recommended for most applications | - |
-| Does the app have a web UI? | Add an [asset canister](#the-default-two-canister-model) | Backend-only canister |
+| Does the app have a web UI? | Add an [asset canister](#frontend-options) | Backend-only canister |
 | Do you need separation of concerns or hit platform limits? | [Canister-per-service](#canister-per-service) | Stay with a single canister |
 | Do you need to scale beyond one subnet? | [Canister-per-subnet](#canister-per-subnet) | Stay on one subnet |