docs: Motoko language landing page

[marc0olo]

Summary

• Overview of Motoko as a language designed for ICP: actor model, orthogonal persistence, async/await, strong typing
• Minimal counter canister example using persistent actor
• Getting started with icp-cli and the @dfinity/motoko recipe
• Standard library section recommending core over base, with migration guidance
• Mops package management
• Documentation sections overview (fundamentals, ICP features, reference) — described without linking to nonexistent internal pages since synced content is not yet present
• Cross-links to quickstart, data persistence, orthogonal persistence, and Rust CDK pages

Sync recommendation

hand-written

[marc0olo]

Review: Motoko language landing page

Must fix

• icp project new is not a valid command: The page uses icp project new my-project --template motoko. The correct command is icp new my-project. There is no --template flag — use --subfolder and --define flags, or just icp new my-project which prompts interactively. (Source: .sources/icp-cli/docs/reference/cli.md:1227)

• icp deploy --local is not a valid flag: There is no --local flag on icp deploy. Use icp deploy (defaults to local) or icp deploy -e local. (Source: .sources/icp-cli/docs/reference/cli.md:771)

• Missing icp network start -d: The "Getting started" section goes straight from icp build to icp deploy --local without starting a local network. The standard flow is icp network start -d then icp deploy. (Source: .sources/icp-cli/docs/quickstart.md:31)

• Migration guide URL is wrong: The page links to https://mops.one/core/docs/migration but .sources/motoko-core/README.md:12 links to https://internetcomputer.org/docs/motoko/base-core-migration. However, that's the old docs site which we must not link to. The base-to-core migration guide is synced from .sources/motoko/doc/md/12-base-core-migration.md and will be available in this site once synced. Suggest linking to the synced page path (even if stub) or flagging with <!-- Needs human verification -->.

• flatMap() replaced chain() claim is misleading: chain() exists in core (Result.mo:131, Option.mo:84). It was not removed or renamed to flatMap(). Either verify the specific claim or remove it from the bullet list.

Suggestions

• core = "0.0.0" version placeholder: Consider using the actual latest version or at minimum a <!-- TODO: verify output --> flag so reviewers know to check this.

• Both Motoko and Rust pages have sidebar: order: 1: One should be adjusted so sidebar ordering is deterministic.

Verified

• persistent actor syntax confirmed valid (.sources/motoko/samples/counter.mo:3, multiple doc examples)
• mo:core/Map, mo:core/Text, mo:core/List modules exist in .sources/motoko-core/src/
• pure/Map, pure/Set, pure/List submodules exist in .sources/motoko-core/src/pure/
• Motoko recipe format @dfinity/motoko@<version> and config keys (main, shrink) verified
• All internal links resolve to existing files
• No dfx references, plain .md, no JSX
• values() vs vals() naming change confirmed

[marc0olo]

Feedback addressed:

• Fixed CLI command: icp project new --template motoko → icp new my-project --subfolder motoko
• Fixed deploy flow: added icp network start -d, removed invalid --local flag, removed redundant icp build
• Updated core version to 2.2.0, added [toolchain] moc = "1.3.0" block
• Fixed migration guide link to internal synced path (base-core-migration.md)
• Replaced inaccurate flatMap()/chain() claim with verified Cycles/ExperimentalCycles rename
• Removed placeholder "Documentation sections" (no value until content is synced)
• Consolidated "Related pages" + "External resources" into single "Further reading" section, removed duplicate links