docs: management canister API reference

[marc0olo]

Summary

• Complete API reference for the IC management canister (aaaaa-aa)
• Documents all methods from the IC interface spec: canister lifecycle, code management (chunked uploads), snapshots (including read/upload), randomness, chain-key signing (ECDSA, Schnorr), vetKD, HTTPS outcalls, Bitcoin API (deprecated), canister logging, subnet/node information, and provisional methods
• Includes ic.did Candid interface file synced from portal for binding generation and type checking
• Includes canister settings table, cycle cost guidance via System API functions, and cross-links to relevant guides
• Covers canister_metadata for custom section access, node_metrics_history (experimental), and subnet_info
• Adds "Synced files from submodules" section to AGENTS.md with portal bump checklist for ic.did

Sync recommendation

informed by dfinity/portal — docs/references/system-canisters/management-canister.mdx, docs/references/ic-interface-spec.md, docs/references/_attachments/ic.did; dfinity/icskills — skills/cycles-management/SKILL.md

[marc0olo]

Review

Must-fix

1. PR reverts two merged content pages to stubs — The diff shows docs/guides/frontends/asset-canister.md (PR docs: asset canister guide #30) and docs/guides/security/access-management.md (PR docs: access management guide #29) being reverted from full content back to stubs. Branch was created from a stale base. Must rebase on main.

2. Missing method: canister_metadata — The IC interface spec defines canister_metadata, which lets canisters read icp:public <name> and icp:private <name> custom sections from any canister. This is a developer-facing method (used for reading Candid interfaces, asset certification metadata, etc.) and should be documented.

3. Upstream comment missing icskills/cdk-rs references — If .sources/cdk-rs or the cycles-management skill were consulted, they must be listed in the <!-- Upstream: --> comment per project rules.

Suggestions

1. Missing methods: node_metrics_history, subnet_info — Both in the IC interface spec. At minimum, brief entries with "experimental" note.

2. Missing snapshot read/upload methods — read_canister_snapshot_metadata, read_canister_snapshot_data, upload_canister_snapshot_metadata, upload_canister_snapshot_data complement the already-documented take_canister_snapshot/load_canister_snapshot.

3. create_canister controller note misleading — Says caller is "not automatically a controller unless included in controllers", but the spec defaults controllers to [caller] when omitted. Could confuse the common case. Consider: "If you provide a controllers list, the caller is only a controller if included in that list. If you omit controllers, it defaults to a list containing only the caller."

4. canister_status missing return fields — ready_for_migration, canister_version not documented.

5. icskills: [] in frontmatter — Should list cycles-management since the page covers it extensively.

6. http_request PUT/DELETE phrasing — "also PUT and DELETE in non-replicated mode" could be clearer that they're only available in non-replicated mode.

Verified

• All 10 internal links resolve to existing files
• No old docs links, no dfx references, plain .md
• Frontmatter valid, <!-- Upstream: --> present, PR has ## Sync recommendation
• Extensive spec verification passed: create_canister caller/cycles, install_code modes and atomicity, canister_info access model, chain-key signing params, sign_with_ecdsa 64-byte encoding, http_request limits, Bitcoin API canister IDs, fetch_canister_logs constraints, canister_settings defaults — all match the IC interface spec
• Page follows Diataxis reference pattern correctly

[marc0olo]

Feedback addressed:

• Rebased on main (removes stale diffs from PRs docs: access management guide #29/docs: asset canister guide #30)
• Added missing canister_metadata method
• Added missing snapshot read/upload methods (read_canister_snapshot_metadata, read_canister_snapshot_data, upload_canister_snapshot_metadata, upload_canister_snapshot_data)
• Added missing node_metrics_history (with experimental note) and subnet_info methods
• Added missing canister_status return fields (canister_version, ready_for_migration)
• Fixed create_canister controller note to cover default behavior (omitting controllers defaults to caller)
• Clarified http_request PUT/DELETE as non-replicated mode only
• Added cycles-management to icskills frontmatter
• Updated <!-- Upstream: --> comment and PR description to include icskills reference

[marc0olo]

Additional changes:

• Added ic.did Candid interface file copied from .sources/portal/docs/references/_attachments/ic.did
• Referenced from management canister page under new "Candid interface" section
• Added "Synced files from submodules" section to AGENTS.md with bump checklist: when portal submodule is bumped, diff ic.did, re-copy if changed, and update management-canister.md plus affected guides
• Recorded decision in .docs-plan/decisions.md