docs: canisters concept page

[marc0olo]

Summary

• Foundational concepts/canisters.md page that most other pages depend on
• Covers canister fundamentals: Wasm execution, message types (update/query/composite), memory model (heap + stable), IDs & principals, lifecycle, controllers, and internals
• Distinguishes official CDKs (Motoko, Rust) from community-supported languages (TypeScript, Python)
• Clarifies query call authenticity: responses are not threshold-signed, should be treated as unverified without certified variables
• Qualifies orthogonal persistence as Motoko-specific in the memory model table

Sync recommendation

informed by dfinity/portal — canisters.mdx, message-execution.mdx

[marc0olo]

Review: concepts/canisters.md — Changes Requested

Good page overall — strong structure, correct CLI commands, good progressive disclosure. A few issues to fix:

1. Broken link: certified-variables.md

The link [certified variables](../reference/certified-variables.md) points to a file that doesn't exist (no stub was created for it). Appears in the "Query calls" section.

Fix: Either link to ../reference/ic-interface-spec.md (which does exist as a stub) with appropriate anchor text, or file a page proposal issue for reference/certified-variables.md and link to the stub once created.

2. Wrong crate URL for ic-stable-structures

The Memory Model section mentions StableBTreeMap (Rust). While this page doesn't directly link the wrong URL, the sister page (app-architecture, PR #4) links ic-stable-structures to docs.rs/ic-cdk which is the wrong crate. If you add a link here, use the correct URL: https://docs.rs/ic-stable-structures/latest/ic_stable_structures/.

✓ Verified

• All CLI commands (icp canister create, icp build, icp canister install, icp deploy, icp canister stop, icp canister delete) verified against .sources/icp-cli/docs/reference/cli.md
• --mode upgrade flag confirmed valid
• All other internal links point to existing stubs
• Correct use of core library (not base) for Motoko

[marc0olo]

Review: concepts/canisters.md (round 2)

Must fix

• Broken link: ../reference/certified-variables.md — This file does not exist. The correct path is ../guides/backends/certified-variables.md. (Flagged in round 1, still unfixed.)

Suggestions

• Link core library — The text mentions "core persistent data structures (Motoko)" but doesn't link it. Add [core](https://mops.one/core/docs) per linking rules.
• Orthogonal persistence nuance — The memory table says heap is "cleared on upgrade." Consider a brief parenthetical "(unless using orthogonal persistence)" since the page already links to that topic and readers may be confused.
• Empty icskills: [] — Consider whether icp-cli is relevant given the CLI examples.

Verified

• All CLI commands (icp canister create, icp build, icp canister install, icp deploy, icp canister stop, icp canister delete, --mode upgrade) verified against .sources/icp-cli/docs/reference/cli.md
• 8 of 9 internal links resolve (only certified-variables.md is broken)
• Memory limits (6 GiB heap, 500 GiB stable) match portal source
• Motoko references use core not base
• No dfx references, no .mdx/JSX
• Frontmatter complete and self-consistent
• All code examples under 30 lines

[marc0olo]

Feedback addressed:

• Fixed broken link ../reference/certified-variables.md → ../guides/backends/certified-variables.md
• Linked core library text to https://mops.one/core/docs
• Added orthogonal persistence caveat to heap memory table row
• Added icp-cli to icskills frontmatter

[marc0olo]

Review: Canisters

Must fix

• CLI commands in concept page: The lifecycle section (lines 93–134) has 6 icp command blocks (canister create, build, canister install, deploy, canister stop, canister delete). Under Diataxis, concept pages explain what and why — not how. The step-by-step CLI invocations belong in guides/canister-management/lifecycle.md. Keep the prose explanations for each stage, drop the code fences, and close with a single link to the lifecycle guide for practical steps. The other two concept pages (network-overview, app-architecture) correctly contain zero CLI commands. Also remove icskills: [icp-cli] from frontmatter since no CLI commands will remain on the page.

Verified

• All 9 internal links resolve to existing files
• CLI command names and flags verified against .sources/icp-cli/docs/reference/cli.md
• External URLs correct (mops.one/core/docs, Wikipedia actor model, dashboard.internetcomputer.org)
• Frontmatter complete and consistent with body content
• No dfx references, no .mdx/JSX
• All code examples under 30 lines
• Relative links with .md extension throughout
• Uses core not base for Motoko standard library
• Content brief from stub fully addressed
• Upstream comment present and accurate

[marc0olo]

Feedback addressed:

• Removed all 6 CLI command code blocks from the lifecycle section (Diataxis: concept pages explain what/why, not how)
• Kept prose explanations for each lifecycle stage
• Updated lifecycle link text to point readers to the guide for CLI commands
• Changed icskills: [icp-cli] to icskills: [] in frontmatter

[Copilot]

Pull request overview

Adds the foundational “Canisters” concept page to the docs, explaining what canisters are and how they work within the Internet Computer’s execution and messaging model.

Changes:

• Replaces the placeholder page with a full conceptual overview (execution model, message types, memory model, IDs/principals, lifecycle, controllers, internals).
• Adds cross-links to related concept and guide pages (cycles/reverse gas, HTTPS outcalls, chain fusion, lifecycle management, certified variables).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[marc0olo]

Feedback addressed:

• Distinguished official CDKs (Motoko, Rust) from community-supported languages (TypeScript, Python) to avoid implying equal official support
• Fixed query call wording: clarified that query responses are not threshold-signed by the subnet and should be treated as unverified without certified variables
• Qualified orthogonal persistence as Motoko-specific in the memory model table