docs(motoko): update guides for new icskills — --default-persistent-actors, inline migration, mops-cli

[marc0olo]

Background

The icskills submodule is currently pinned at 1d125a9; remote origin/main is at 4713d1e. That commit adds three new skills and substantially rewrites the existing motoko skill:

Skill	Change
motoko	Major overhaul: --default-persistent-actors is now the standard; dot notation (M0236) and implicit comparators (M0237) required; mixins added; moc 1.7.0 pinned
migrating-motoko	New: (with migration = ...) inline syntax for one-shot state migrations
migrating-motoko-enhanced	New: multi-step migration with a migrations/ directory and mops-managed --enhanced-migration flag
mops-cli	New: full toolchain coverage (check, build, test, lint, migrate, toolchain)

Scope

This is a single PR that bumps the submodule from 1d125a9 to 4713d1e and updates the docs to match. The two must ship together: bumping without updating the docs would leave persistent actor in every code example while the pinned skill recommends plain actor {} with --default-persistent-actors.

Required changes

Bump icskills submodule

• Pin .sources/icskills to 4713d1e

Add --default-persistent-actors and drop persistent actor from code examples

With the flag in mops.toml, plain actor { } works and all state is persistent by default. Keeping persistent actor in code examples while recommending the flag is contradictory.

[moc]
args = ["--default-persistent-actors", "-W=M0236,M0237,M0223"]

• Add --default-persistent-actors to the recommended mops.toml setup in guides/backends/data-persistence.mdx, concepts/orthogonal-persistence.md, and guides/canister-management/lifecycle.mdx
• Replace persistent actor with actor in all Motoko code examples (approx. 50 occurrences in 30+ files — grep first to get the full list)
• Keep persistent actor only in explanatory prose where the keyword itself is being discussed

Files known to contain persistent actor in code blocks:

guides/backends/data-persistence.mdx
guides/backends/timers.mdx
guides/backends/certified-variables.md
guides/chain-fusion/bitcoin.mdx
guides/chain-fusion/ethereum.mdx
guides/chain-fusion/solana.mdx
guides/chain-fusion/exchange-rates.mdx
guides/canister-management/lifecycle.mdx
guides/canister-management/cycles-management.mdx
guides/security/canister-upgrades.md
guides/security/access-management.mdx
guides/canister-calls/inter-canister-calls.mdx
guides/canister-calls/parallel-inter-canister-calls.mdx
guides/digital-assets/ledgers.mdx
guides/authentication/internet-identity.mdx
references/application-canisters.md

Document (with migration = ...) inline migration syntax

The canister upgrade guides recommend avoiding preupgrade/postupgrade but say nothing about what to do when a field type changes or a field is renamed. That answer is now the inline migration syntax.

• Add a "Changing persistent state" subsection to guides/canister-management/lifecycle.mdx covering (with migration = ...)
• Update guides/security/canister-upgrades.md to reference the migration syntax for incompatible type changes

Update timer re-registration pattern

guides/backends/timers.mdx uses system func postupgrade to re-register timers. The new skill identifies timer IDs as the canonical transient var use case.

• Update guides/backends/timers.mdx to present transient var as the preferred pattern and move postupgrade to a note for legacy or complex cases

Document mops CLI commands in developer tools

references/developer-tools.md mentions mops but not its primary commands.

• Add coverage of mops check, mops build, mops test, mops lint, and mops migrate to references/developer-tools.md

Out of scope

• postupgrade in certified-variables.md and certification.md: legitimate use for re-establishing certifications after upgrade, not data migration
• docs/languages/motoko/: auto-synced from caffeinelabs/motoko, not manually edited

Prerequisite

Wait for PR #208 to merge before starting. Several affected files are modified by that PR.

[marc0olo]

"In Motoko, use persistent actor instead of manual pre_upgrade/post_upgrade" (e.g. in canister lifecycle) probably also doesn't make much sense anymore. it should rather recommend using stable variables which is the default mode going forward and advertised/enforced via --default-persistent-actors. maybe it isn't even worth mentioning any longer 🤔