docs: subnet selection guide

[marc0olo]

Summary

• When to specify a subnet: data residency, security requirements, colocation with existing canisters, storage capacity
• Subnet types: application (13-node), fiduciary (34-node, ~2.6× cost), European (GDPR-aligned), system (not for arbitrary deployment)
• How to find a subnet ID via ICP Dashboard
• --subnet flag for icp deploy and icp canister create (syntax verified against icp-cli reference)
• --proxy flag for colocation with an existing canister
• Troubleshooting: subnet not found, migrating a canister to a different subnet using snapshots + icp canister migrate-id
• Note: --subnet-type (dfx) and --next-to (dfx) have no direct icp-cli equivalents; uses --subnet <PRINCIPAL_ID> only

Sync recommendation

informed by dfinity/portal — subnet-types.mdx, deploying-smart-contracts.mdx; dfinity/icp-cli — docs/reference/cli.md

[marc0olo]

Review: Subnet Selection

Must fix

• dfx reference on line 93: The page says "This is the icp-cli equivalent of the dfx --next-to pattern." dfx is banned per CLAUDE.md. Remove the dfx reference entirely — just describe the --proxy mechanism in its own terms. Suggested replacement: "This is useful when you already have a deployed canister and want new canisters to live on the same subnet."

• Threshold signature key loss warning is too narrow: The troubleshooting section says "migrating away from the fiduciary subnet means losing access to any threshold signature keys (tECDSA or tSchnorr) derived by the original canister." This is inaccurate: the key loss risk applies to any canister ID change, not specifically to migrating away from the fiduciary subnet. Per .sources/icp-cli/docs/guides/canister-migration.md: "A canister's derived keys — and any addresses or public keys derived from them — are permanently tied to its ID." Even a snapshot transfer to a new canister on a different application subnet would lose those keys. Broaden the warning to cover all ID changes, not just fiduciary migrations.

• Missing vetKeys in the key loss warning: The icp-cli migration guide explicitly states that both threshold signature keys (tECDSA/tSchnorr) AND vetKeys are lost when the canister ID changes ("VetKey derivation similarly includes the canister's principal. A new ID produces entirely different decryption keys, making previously encrypted data inaccessible."). The page only mentions tECDSA/tSchnorr. Add vetKeys to the warning.

Suggestions

• Fiduciary subnet principal ID discrepancy between sources: The PR page uses pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeez-fez7a-iae (from .sources/icp-cli), while .sources/portal lists pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeq5-fk5o7-yae. The page is consistent with the icp-cli guide, which is the more authoritative source for icp-cli tooling. The ICP Dashboard is the ground truth for the live subnet ID — this warrants a human verification. Both sources agree on the pzp6e prefix. Since the full principal is used only as an example in CLI commands (not a critical functional claim), this is low risk. Consider adding a note pointing readers to the ICP Dashboard to look up the current ID.

• "ICP Dashboard" references without links: The application subnet section (line 25) and storage section (line 99) both mention "the ICP Dashboard" without a hyperlink, while "Finding a subnet ID" (line 61) links it. Consider linking the first occurrence of ICP Dashboard in the page rather than waiting until section 5. As written, a reader seeing "The ICP Dashboard shows current load..." in the first subnet-types section has no clickable link.

Verified

• All internal links resolve: ../../reference/cycles-costs.md, ../../reference/subnet-types.md, snapshots.md, ../../concepts/network-overview.md all exist as .md files.
• No dfx references in CLI code blocks — only icp deploy and icp canister create are used in code examples.
• All CLI commands verified against .sources/icp-cli/docs/reference/cli.md: icp deploy --subnet, icp canister create --subnet, icp canister create --proxy, and icp canister migrate-id are all real commands with the correct flags.
• No banned URL patterns (internetcomputer.org/docs/ or docs.internetcomputer.org) — external links are limited to dashboard.internetcomputer.org.
• Frontmatter complete: title, description, and sidebar.order all present and consistent with body.
• <\!-- Upstream: --> comment present at end of page listing both source files.
• Subnet IDs verified against .sources/portal: bkfrj (European), tdb26 (NNS), uzr34 (II/etc), w4rem (Bitcoin) all match portal source.
• Node counts verified: 13-node application subnets, 34-node fiduciary subnet — confirmed in portal source.
• Cost multiplier claim "approximately 2.6x" verified: 34/13 = 2.615 ≈ 2.6 ✓
• Storage threshold 750 GiB verified against .sources/portal/docs/building-apps/essentials/gas-cost.mdx ✓
• "10 years of projected costs" claim verified against portal source ✓
• --proxy flag creates canister on same subnet as proxy confirmed in icp-cli reference ✓
• Proxy canister proxy method requirement confirmed in icp-cli reference ✓
• Page structure: orient → subnet types → default behavior → how-to → troubleshooting → next steps ✓
• Content brief coverage: application subnets, system subnets (including Bitcoin/II), European subnet, fiduciary subnet, colocation, CLI commands, cost multipliers, storage constraints — all addressed ✓
• No .mdx syntax in .md file ✓

[marc0olo]

<!-- feedback-addressed -->
Feedback addressed for PR #81 (docs/guides/canister-management/subnet-selection.md):

Changes applied

Must-fix items

1. Removed banned dfx reference (line 93) — The sentence "This is the icp-cli equivalent of the dfx --next-to pattern." was removed. Replaced with: "This is useful when you already have a deployed canister and want new canisters to live on the same subnet." — dfx is banned per CLAUDE.md.

2. Broadened key loss warning — The warning previously said "migrating away from the fiduciary subnet means losing access to any threshold signature keys (tECDSA or tSchnorr) derived by the original canister." This is inaccurate: the key loss risk applies to any canister ID change, not specifically to fiduciary subnet migrations. Cross-checked against .sources/icp-cli/docs/guides/canister-migration.md: "A canister's derived keys — and any addresses or public keys derived from them — are permanently tied to its ID." Updated to: "Note that any canister ID change means losing access to any threshold signature keys (tECDSA, tSchnorr) and vetKeys derived by the original canister — these are cryptographically bound to the canister ID."

3. Added vetKeys to key loss warning — The icp-cli migration guide explicitly states: "VetKey derivation similarly includes the canister's principal. A new ID produces entirely different decryption keys, making previously encrypted data inaccessible." The original text only listed tECDSA and tSchnorr. Added vetKeys to the warning.

Suggestions applied

4. Added ICP Dashboard links in application subnets section and storage section — The first occurrence in "Application subnets" (previously unlinked "The ICP Dashboard shows...") is now linked to https://dashboard.internetcomputer.org/subnets. The occurrence in the storage section ("check the current utilization of candidate subnets on the ICP Dashboard") is also now linked.

5. Added subnet ID verification tip — Following the fiduciary subnet principal ID discrepancy note in the review (sources disagree on the full principal, both agree on the pzp6e prefix), added a tip block after the CLI examples directing readers to verify current subnet IDs on the ICP Dashboard before using them in production scripts.

Items skipped

None — all feedback items were factually correct and consistent with CLAUDE.md rules and source material. All must-fix items were applied, and both suggestions were applied as they improve page usability with no downsides.

Build status

The npm run build failure is pre-existing and unrelated to this PR — it is caused by .sources/examples being an uninitialized submodule in this worktree, which affects docs/guides/backends/https-outcalls.mdx. The build fails identically before and after our changes, confirming our changes introduce no new build errors.