fix(motoko): restore missing pages, fix nav order, rewrite stale links

.github/workflows/deploy-ic.yml

@@ -24,10 +24,10 @@ jobs:
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
-      - name: Initialize examples submodule
+      - name: Initialize submodules
         run: |
           git config --global url."https://github.com/".insteadOf "git@github.com:"
-          git submodule update --init --depth 1 .sources/examples
+          git submodule update --init --depth 1 .sources/examples .sources/motoko
 
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:

.github/workflows/preview-deployment.yml

@@ -15,10 +15,10 @@ jobs:
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
-      - name: Initialize examples submodule
+      - name: Initialize submodules
         run: |
           git config --global url."https://github.com/".insteadOf "git@github.com:"
-          git submodule update --init --depth 1 .sources/examples
+          git submodule update --init --depth 1 .sources/examples .sources/motoko
 
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:

docs/developer-tools/index.md

@@ -1,11 +1,11 @@
 ---
 title: "Developer tools"
-description: "Overview of the ICP developer toolchain: icp-cli, CDKs, JS SDK, PocketIC, and more"
+description: "Overview of the ICP developer toolchain: icp-cli, Motoko, CDKs, JS SDK, PocketIC, and more"
 sidebar:
   hidden: true
 ---
 
-Developer tools are used to create, manage, and interact with canisters. ICP provides tooling across several categories: command-line tools, canister development kits (CDKs), client libraries, testing tools, browser-based IDEs, and Candid tooling.
+Developer tools are used to create, manage, and interact with canisters. ICP provides tooling across several categories: command-line tools, Motoko, canister development kits (CDKs), client libraries, testing tools, browser-based IDEs, and Candid tooling.
 
 ## Command-line tools
 
@@ -44,18 +44,38 @@ Quill is suited for:
 Resources:
 - [Quill GitHub repo](https://github.com/dfinity/quill)
 
-## Canister development kits (CDKs)
-
-A canister development kit (CDK) provides a programming language with the libraries and toolchain support needed to compile code to WebAssembly and interact with the ICP system API.
-
-### Motoko
+## Motoko
 
-Motoko is ICP's native programming language, designed around the actor model, orthogonal persistence, and asynchronous message passing. It compiles directly to WebAssembly and includes a standard library (`mo:core`) with modules for common data structures, cryptography, and system interaction.
+Motoko is ICP's native programming language, designed specifically for the actor model, orthogonal persistence, and asynchronous message passing. It compiles directly to WebAssembly without requiring a separate CDK and includes a standard library (`mo:core`) with modules for common data structures, cryptography, and system interaction.
 
 Third-party Motoko libraries are distributed through [Mops](https://mops.one), the Motoko package manager. Use `mops add <package>` to add a dependency to your project.
 
 For language documentation, see [languages/motoko](../languages/motoko/index.md).
 
+### Motoko VS Code extension
+
+The [Motoko extension for VS Code](https://github.com/caffeinelabs/vscode-motoko) adds Motoko language support to VS Code: syntax highlighting, type checking, auto-completion, and inline diagnostics. Install by searching for "Motoko" in the VS Code extensions panel.
+
+### mo-doc
+
+`mo-doc` generates documentation for Motoko source code from `///` doc comments, producing HTML (default), Markdown (`--format plain`), or AsciiDoc (`--format adoc`) output.
+
+Install: `mo-doc` is bundled inside the Motoko compiler tarball. Download the archive for your platform from the [Motoko releases page](https://github.com/caffeinelabs/motoko/releases), then extract it; the binary is at `bin/mo-doc` inside the archive.
+
+```bash
+# Platform: Darwin-arm64, Darwin-x86_64, Linux-aarch64, Linux-x86_64
+tar xzf motoko-<platform>-<version>.tar.gz
+./bin/mo-doc                                    # HTML output to ./docs
+./bin/mo-doc --format plain --output ./api-docs # Markdown output to ./api-docs
+./bin/mo-doc --source ./src --output ./out      # custom source and output paths
+```
+
+For how to write doc comments in Motoko source, see [Comments](../languages/motoko/fundamentals/basic-syntax/comments.md).
+
+## Canister development kits (CDKs)
+
+A canister development kit (CDK) provides an existing programming language with the libraries and toolchain support needed to compile code to WebAssembly and interact with the ICP system API.
+
 ### Rust CDK (`ic-cdk`)
 
 The Rust CDK (`ic-cdk`) is the official DFINITY-maintained library for building canisters in Rust. It exposes the ICP system API as safe Rust abstractions, including:
@@ -144,14 +164,6 @@ Limitations:
 - Projects are limited to 5 MB and 2 canisters
 - ICP Ninja is not a replacement for icp-cli for production workflows
 
-## Editor tooling
-
-### Motoko VS Code extension
-
-The [Motoko extension for VS Code](https://github.com/dfinity/vscode-motoko) (`dfinity/vscode-motoko`) adds Motoko language support to VS Code: syntax highlighting, type checking, auto-completion, and inline diagnostics.
-
-Install by searching for "Motoko" in the VS Code extensions panel, or visit the [vscode-motoko repository](https://github.com/dfinity/vscode-motoko) for details.
-
 ## Candid tools
 
 ### didc
@@ -162,12 +174,12 @@ Install: download a prebuilt binary from the [releases page](https://github.com/
 
 Resources:
 - [Candid GitHub repo](https://github.com/dfinity/candid)
-- Candid specification: [candid-spec.md](candid-spec.md)
+- Candid specification: [candid-spec.md](../references/candid-spec.md)
 
 ## Next steps
 
 - **Start building:** [Quickstart](../getting-started/quickstart.md): deploy your first canister with icp-cli
 - **Rust development:** [Rust language guide](../languages/rust/index.md)
 - **Motoko development:** [Motoko language guide](../languages/motoko/index.md)
 
-<!-- Upstream: informed by dfinity/portal — docs/building-apps/developer-tools/dev-tools-overview.mdx, docs/building-apps/developer-tools/icp-ninja.mdx, docs/building-apps/developer-tools/cdks/index.mdx, docs/tutorials/developer-liftoff/level-1/1.2-dev-env.mdx; dfinity/icp-cli — docs/telemetry.md, docs/guides/installation.md, docs/guides/creating-recipes.md, docs/guides/creating-templates.md; dfinity/candid — README.md; dfinity/icp-js-sdk-docs — core/latest.zip (agent, candid, principal, identity), auth/latest.zip, bindgen/latest.zip, pic-js/latest.zip -->
+<!-- Upstream: informed by dfinity/portal — docs/building-apps/developer-tools/dev-tools-overview.mdx, docs/building-apps/developer-tools/icp-ninja.mdx, docs/building-apps/developer-tools/cdks/index.mdx, docs/tutorials/developer-liftoff/level-1/1.2-dev-env.mdx; dfinity/icp-cli — docs/telemetry.md, docs/guides/installation.md, docs/guides/creating-recipes.md, docs/guides/creating-templates.md; dfinity/candid — README.md; dfinity/icp-js-sdk-docs — core/latest.zip (agent, candid, principal, identity), auth/latest.zip, bindgen/latest.zip, pic-js/latest.zip; caffeinelabs/motoko — doc/md/motoko-tooling/3-mo-doc.md -->

docs/guides/backends/data-persistence.mdx

@@ -253,7 +253,7 @@ When upgrading a Motoko canister, the type of every persistent field must be com
 
 **Unsafe changes (will trap on upgrade):**
 - Remove or rename a persistent field
-- Change a field's type (e.g., `Nat` → `Int`)
+- Change a field's type to an incompatible type (e.g., `Int` → `Float`, or `Nat` → `Text`)
 - Change a non-optional field to a different type
 
 </TabItem>

docs/languages/motoko/fundamentals/actors-async.md → docs/languages/motoko/fundamentals/actors/actors-async.md

@@ -4,7 +4,7 @@ description: "Motoko language documentation"
 title: "Actors & async data"
 ---
 
-The actor programming model was designed to solve concurrency issues by encapsulating [state](/languages/motoko/fundamentals/state) and computation within independent units called **actors**.
+The actor programming model was designed to solve concurrency issues by encapsulating [state](/languages/motoko/fundamentals/actors/state) and computation within independent units called **actors**.
 
 The actor model is built on four key principles:
 
@@ -68,35 +68,7 @@ A trap will only revoke changes made since the last commit point. In particular,
 
 Consider the following stateful `Atomicity` actor:
 
-```motoko
-persistent actor Atomicity {
-
-  transient var s = 0;
-  transient var pinged = false;
-
-  public func ping() : async () {
-    pinged := true;
-  };
-
-  // an atomic method
-  public func atomic() : async () {
-    s := 1;
-    ignore ping();
-    ignore 0/0; // trap!
-  };
-
-  // a non-atomic method
-  public func nonAtomic() : async () {
-    s := 1;
-    let f = ping(); // this will not be rolled back!
-    s := 2;
-    await f;
-    s := 3; // this will not be rolled back!
-    await f;
-    ignore 0/0; // trap!
-  };
-
-};
+```motoko no-repl file=<motokoExamples>/atomicity.mo
 ```
 
 Calling the shared function `atomic()` results in an error because it traps before completing. Since the trap happens before any `await` or return, all changes are discarded. The variable `s` stays at 0, and `pinged` remains false. Even though `atomic()` calls `ping()`, that message is only queued and never sent because no commit point is reached.
@@ -108,20 +80,7 @@ Calling `nonAtomic()` also fails with an error, but the state is partially updat
 
 Here is an example program that uses async functions:
 
-```motoko
-persistent actor Counter {
-
-  var count = 0;
-
-  public shared func inc() : async () { count += 1 };
-
-  public shared func read() : async Nat { count };
-
-  public shared func bump() : async Nat {
-    count += 1;
-    count;
-  };
-};
+```motoko file=<motokoExamples>/counter-actor.mo
 ```
 
 The `Counter` actor declares one field and three public, shared functions:
@@ -257,7 +216,7 @@ In other languages without these features, developers often need to use advanced
 
 To demonstrate how asynchronous actors work, consider the following example.
 
-Customers place orders at a pizza restaurant, but the chef can only make one pizza at a time. Orders are taken **[asynchronously](/languages/motoko/fundamentals/actors-async#async--await)**, meaning customers do not have to wait for previous orders to be completed before placing their own. However, each pizza is prepared sequentially. This is representative of an asynchronous actor.
+Customers place orders at a pizza restaurant, but the chef can only make one pizza at a time. Orders are taken **[asynchronously](/languages/motoko/fundamentals/actors/actors-async#async--await)**, meaning customers do not have to wait for previous orders to be completed before placing their own. However, each pizza is prepared sequentially. This is representative of an asynchronous actor.
 <!-- TODO(FUTURE): It would be cleaner to use a Deque or Queue pushing new order to the end and popping the next order to make from the front. -->
 ```motoko no-repl
 import Array "mo:core/Array";