refactor(concepts): move canister control content from principals to canisters

The controller table and upgrade hook sequence belong conceptually with
canisters, not principals. principals.md is now focused on identity only
(principal classes + caller semantics). canisters.md absorbs the control
structure table and detailed upgrade steps from the Canister Control
Learn Hub article.

Author: marc0olo

docs/concepts/canisters.md

@@ -90,7 +90,13 @@ Installing uploads a Wasm module to the canister and runs its initialization log
 
 ### Upgrade
 
-Upgrading replaces the canister's Wasm module while preserving stable memory. The system runs a pre-upgrade hook (to save heap data to stable memory if needed), swaps the Wasm, then runs a post-upgrade hook (to restore data).
+Upgrading replaces the canister's Wasm module while preserving stable memory. The runtime executes three steps atomically:
+
+1. `pre_upgrade` (or `system func preupgrade` in Motoko): save any heap data to stable memory before the code swap.
+2. New Wasm module is installed.
+3. `post_upgrade` (or `system func postupgrade`): read data back from stable memory into the new heap layout.
+
+If `pre_upgrade` traps, the upgrade is aborted and the canister continues running the old code. If `post_upgrade` traps, the new code is installed but the canister is left in a failed state. If a canister ensures all persistent data is always in stable memory, steps 1 and 3 can be left empty.
 
 ### Stop and delete
 
@@ -102,7 +108,16 @@ For step-by-step CLI commands, see [Canister lifecycle management](../guides/can
 
 Controllers are principals (users or other canisters) that have permission to manage a canister: upgrade its code, change its settings, stop it, or delete it.
 
-If a canister has **no controllers**, it is immutable: no one can change its code or settings. This is a strong guarantee for users who want to verify that a canister's behavior will never change.
+The control structure can take several forms:
+
+| Control structure | Who is the controller | Effect |
+|---|---|---|
+| Centralized | A single developer's principal | Full developer control; standard during development |
+| Multi-signature | A multi-signer wallet like [Orbit](https://orbitwallet.io/) | Requires multiple keys to approve any change |
+| SNS-governed | An SNS governance canister | Upgrades require a governance proposal voted on by token holders |
+| No controller | Empty controller list | Immutable canister; code can never be changed |
+
+If a canister has **no controllers**, it is immutable: no one can change its code or settings. This is a strong trust guarantee for users. Immutability can be verified on the [ICP Dashboard](https://dashboard.internetcomputer.org).
 
 ## Canister internals
 
@@ -127,9 +142,9 @@ This has a practical implication: if a canister modifies state and then makes an
 ## Next steps
 
 - [Cycles](cycles.md): how canisters pay for computation
-- [Principals](principals.md): the identity model and canister controllers
+- [Principals](principals.md): the identity model and caller authentication
 - [App architecture](app-architecture.md): how canisters fit into application design
 - [Canister lifecycle](../guides/canister-management/lifecycle.md): practical guide to managing canisters
 - [Network overview](network-overview.md): the infrastructure canisters run on
 
-<!-- Upstream: informed by dfinity/portal docs/building-apps/essentials/canisters.mdx, message-execution.mdx; informed by Learn Hub articles "Canister Smart Contracts", "Computational Model" (migrated, source retired) -->
+<!-- Upstream: informed by dfinity/portal docs/building-apps/essentials/canisters.mdx, message-execution.mdx; informed by Learn Hub articles "Canister Smart Contracts", "Computational Model", "Canister Control" (migrated, source retired) -->

docs/concepts/index.md

@@ -12,7 +12,7 @@ Understand the ideas behind the Internet Computer before you build on it. These
 - **[Network Overview](network-overview.md)**: Subnets, nodes, consensus, and boundary nodes.
 - **[Application Architecture](app-architecture.md)**: How ICP applications are structured: canisters, frontends, and inter-canister communication.
 - **[Canisters](canisters.md)**: Programs that run WebAssembly, hold state, serve HTTP, and pay for their own compute.
-- **[Principals](principals.md)**: The identity model: users, canisters, anonymous calls, and canister control.
+- **[Principals](principals.md)**: The identity model: who can call a canister, and how caller identity works.
 
 ## Core capabilities
 

docs/concepts/principals.md

@@ -1,6 +1,6 @@
 ---
 title: "Principals"
-description: "What principals are on ICP: the identity model, principal classes, canister control, and how authentication works"
+description: "What principals are on ICP: the five principal classes and how caller identity works in practice"
 ---
 
 A **principal** is any entity that can authenticate with the Internet Computer and be identified when calling a canister. Principals are the building block of identity and access control on ICP: canisters use them to identify callers, enforce permissions, and determine which entities have control over which resources.
@@ -31,42 +31,10 @@ Unsigned request → 2vxsx-fae (anonymous principal)
 
 This means that from a canister's perspective, all callers are principals. There is no separate "user object" or session token: the principal is the identity.
 
-## Canister control
-
-Canisters are managed by their **controllers**: a list of principals (users, other canisters, or DAOs) that have permission to perform management operations on the canister. Controllers can:
-
-- Upgrade the canister's Wasm module.
-- Change canister settings (compute allocation, memory allocation, freezing threshold).
-- Start or stop the canister.
-- Delete the canister and claim its remaining cycles.
-- Add or remove other controllers.
-
-The control structure can take several forms:
-
-| Control structure | Who is the controller | Effect |
-|---|---|---|
-| Centralized | A single developer's principal | Full developer control; standard for development |
-| Multi-signature | A multi-signer wallet like [Orbit](https://orbitwallet.io/) | Requires multiple keys to approve changes |
-| DAO-governed | An SNS governance canister | Upgrades require a governance proposal |
-| No controller | Empty controller list | Immutable canister; code can never be changed |
-
-When a canister has no controllers, it is **immutable**: no one can modify its code or settings. Users who want to trust that a canister's behavior will never change can verify this on the [ICP Dashboard](https://dashboard.internetcomputer.org).
-
-## Canister upgrades and stable memory
-
-When a controller upgrades a canister, the new Wasm module replaces the old one. By default, Wasm heap memory is cleared on upgrade because the new module may have a different memory layout. However, **stable memory is always preserved** across upgrades: it is explicitly managed by the canister (via system API calls) and designed to survive code changes.
-
-The runtime runs upgrade hooks atomically around the code swap:
-1. `pre_upgrade` (or `system func preupgrade` in Motoko): save any heap data to stable memory.
-2. New Wasm module is installed.
-3. `post_upgrade` (or `system func postupgrade`): read data back from stable memory into the new heap layout.
-
-If the `pre_upgrade` hook traps, the upgrade is aborted and the canister continues running the old code. If `post_upgrade` traps, the new code is installed but the canister is left in a failed state.
-
 ## Next steps
 
-- [Canisters](canisters.md): how canisters work, lifecycle, and message types
+- [Canisters](canisters.md): how canisters work, controllers, lifecycle, and message types
 - [Authentication](../guides/authentication/internet-identity.md): integrating Internet Identity and other authentication providers
 - [IC Interface Specification: Principals](../references/ic-interface-spec/index.md#principal): the formal specification
 
-<!-- Upstream: informed by Learn Hub articles "What is a Principal?", "Canister Control" (migrated, source retired) -->
+<!-- Upstream: informed by Learn Hub article "What is a Principal?" (migrated, source retired) -->