docs: sync content against the ten upstream releases the watcher surfaced

.agents/upstream-tracking.md

@@ -7,18 +7,19 @@ Upstream repos fall into three groups, and the group decides the procedure.
 | | Vendored (submodule) | Watched | Reference |
 |---|---|---|---|
 | Which | `motoko`, `internetidentity`, `examples` | the `watched` array in `.sources/upstream.json` | the `reference` array |
-| Why | the build opens their files | a release can silently invalidate a lot of published content | drawn on too lightly for a weekly issue |
+| Why | the build opens their files | a release can silently invalidate a lot of published content | drawn on too lightly, or another check already catches the drift |
 | Pin | the gitlink | `pinned` in `upstream.json` | none; verify against the latest release |
-| Notified | yes | yes | no |
+| Release issue | only `examples`, and only when a quoted file moved | yes | no |
 
 Deciding between the last two is a judgment about blast radius, and the `why`
 field on each `reference` entry records the footprint that decided it. Promote an
 entry to `watched` if its footprint grows.
 
 `motoko` and `internetidentity` have their own weekly sync workflows that open
-the bump PR directly. `examples` and the `watched` repos are covered by the
-weekly **Upstream release check**, which opens an issue. `reference` repos are
-not checked at all.
+the bump PR directly. The `watched` repos are covered by the weekly **Upstream
+release check**, which opens an issue whenever one moves. That same check covers
+`examples`, but opens an issue only when the range touched a file a `snippet=`
+quotes. `reference` repos are not checked at all.
 
 ## Why only three are vendored
 
@@ -167,10 +168,14 @@ When `icp-cli` moves to a new minor:
 
 Only the project maintainer bumps submodule refs.
 
-`examples` tracks a branch and is checked by the same **Upstream release check**
-workflow, which opens an issue when the gitlink falls behind that branch. Its pin
-lives in git, so `upstream.json` records only the branch to compare against and
-what a bump affects.
+`examples` is checked, but only for the case the build cannot see. A `snippet=`
+path or `#region` marker that stops resolving already fails the build. What the
+build cannot notice is an example being corrected upstream while still
+resolving, which leaves the docs quoting old code with everything green. So its
+entry carries `pathFilter: "snippets"`: the check intersects the files changed
+between the pinned gitlink and the branch head with every file a `snippet=`
+quotes, and opens an issue only when they overlap, naming the files. Any other
+commit on that repo stays silent.
 
 `motoko` and `internetidentity` are not in `upstream.json`: `sync-motoko.yml` and
 `sync-ii-spec.yml` already check for a new release, run the sync, and open the

.sources/upstream.json

@@ -2,60 +2,69 @@
   "$comment": [
     "Every upstream this repo tracks, in three groups.",
     "",
-    "`vendored` are submodules whose pin has no sync workflow of its own. Their pin",
-    "is the gitlink in git, not a field here, so it has one source of truth; the entry",
-    "records which branch to compare against and what a bump affects. `motoko` and",
-    "`internetidentity` are absent on purpose: sync-motoko.yml and sync-ii-spec.yml",
-    "already check for a new release and open the bump PR themselves.",
-    "",
     "`watched` are repos where a release can silently invalidate a lot of published",
     "content, so they get a pinned ref and a weekly issue when they move. Verify",
     "claims against the pinned ref, not against main, so a review is reproducible.",
     "",
+    "`vendored` are submodules whose pin has no sync workflow of its own. Their pin",
+    "is the gitlink, so git stays the single source of truth. `motoko` and",
+    "`internetidentity` are absent on purpose: sync-motoko.yml and sync-ii-spec.yml",
+    "already release-check and open the bump PR themselves.",
+    "",
     "`reference` are repos the docs draw on too lightly to be worth a weekly issue:",
     "each `why` records the footprint that decided it. They carry no pin. Verify",
-    "against the latest release on demand; the surface is small enough that the next",
-    "edit to those pages catches any drift. Promote one to `watched` if its footprint",
-    "grows.",
+    "against the latest release on demand. Promote one if that changes.",
     "",
-    "scripts/check-upstream-releases.mjs checks `vendored` and `watched` only, and",
+    "scripts/check-upstream-releases.mjs checks `watched` and `vendored`, and",
     ".github/workflows/upstream-releases.yml opens an issue per repo that moved.",
     "See AGENTS.md 'Source material' and .agents/upstream-tracking.md.",
     "",
     "Fields (watched):",
     "  repo        owner/name on GitHub",
+    "  name        optional, when one repo releases several things independently",
     "  pinned      the ref docs are currently verified against",
     "  track       where releases appear: 'release' (git tags matching tagPattern),",
     "              'crate' (crates.io, needs `crate`), 'npm' (npm registry, needs",
-    "              `package`), or 'commit' (no releases; the default branch head).",
-    "              Entries in `vendored` use 'branch' and name the branch instead.",
+    "              `package`), or 'commit' (no releases; the default branch head)",
     "  tagPattern  anchored JS regex selecting the tags that count as a release",
     "  verify      file whose diff between the two refs is the review payload",
     "  affects     what to re-check in docs/ when this moves",
-    "  reference   authoritative published docs for the topic"
+    "  reference   authoritative published docs for the topic, deliberately the",
+    "              living version rather than a pinned one: an issue exists because a",
+    "              NEW release shipped, so a maintainer opening it wants the docs for",
+    "              that release, not for the version being replaced. This is why the",
+    "              icp-cli entry uses the bare root while AGENTS.md requires a",
+    "              versioned slug in docs/ pages, and why every other entry here",
+    "              points at docs.rs/latest, mops.one, js.icp.build or a branch.",
+    "",
+    "Fields (vendored): path, repo, track 'branch', branch, affects, and an optional",
+    "pathFilter. 'snippets' reports only when the range touched a file quoted by a",
+    "`snippet=` in docs/, so an unrelated commit on an active repo stays silent."
   ],
   "vendored": [
     {
       "path": ".sources/examples",
       "repo": "dfinity/examples",
       "track": "branch",
       "branch": "master",
-      "affects": "Every `snippet=` path and `#region` marker resolved at build time by plugins/remark-snippet.mjs. A renamed region is a build error, so verify each one after bumping."
+      "pathFilter": "snippets",
+      "affects": "Bump the submodule and re-read the affected pages: the example moved on, so the code the docs quote is behind. The build already fails if a `snippet=` path or `#region` marker stops resolving, so this reports the case the build cannot see, an example that changed while still resolving.",
+      "reference": "https://github.com/dfinity/examples"
     }
   ],
   "watched": [
     {
       "repo": "dfinity/icp-cli",
-      "pinned": "v1.1.0",
+      "pinned": "v1.3.0",
       "track": "release",
       "tagPattern": "^v\\d+\\.\\d+\\.\\d+$",
       "verify": "docs/reference/cli.md",
-      "affects": "Every `icp` command and flag in docs/. A new minor also moves the cli.internetcomputer.org link slug (AGENTS.md 'Linking rules'). NOTE: the doc links were moved to the 1.3 slug in #354, but the commands themselves were last verified against v1.1.0, so the first bump of this pin carries that verification pass.",
+      "affects": "Every `icp` command and flag in docs/. A new minor also moves the cli.internetcomputer.org link slug (AGENTS.md 'Linking rules'), so check the slug procedure in .agents/upstream-tracking.md when the minor changes.",
       "reference": "https://cli.internetcomputer.org/"
     },
     {
       "repo": "dfinity/motoko-core",
-      "pinned": "v2.4.0",
+      "pinned": "v2.6.1",
       "track": "release",
       "tagPattern": "^v\\d+\\.\\d+\\.\\d+$",
       "affects": "Every `mo:core` import and API signature in Motoko code blocks.",
@@ -64,15 +73,15 @@
     },
     {
       "repo": "dfinity/cdk-rs",
-      "pinned": "0.20.1",
+      "pinned": "0.20.2",
       "track": "crate",
       "crate": "ic-cdk",
       "affects": "`ic-cdk` APIs in Rust code blocks. The repo stopped tagging releases (its newest bare-semver tag is two minors behind the published crate), so the crate version on crates.io is the release identity. Read the sections newer than the pin in https://github.com/dfinity/cdk-rs/blob/master/ic-cdk/CHANGELOG.md, then grep docs/ for the symbols they name. `ic-cdk-timers` and `ic-cdk-executor` version separately; check whether they moved too.",
       "reference": "https://docs.rs/ic-cdk/latest/ic_cdk/"
     },
     {
       "repo": "dfinity/icp-js-core",
-      "pinned": "v5.4.0",
+      "pinned": "v6.1.0",
       "track": "release",
       "tagPattern": "^v\\d+\\.\\d+\\.\\d+$",
       "verify": "CHANGELOG.md",
@@ -81,7 +90,7 @@
     },
     {
       "repo": "dfinity/icp-js-canisters",
-      "pinned": "3.5.0",
+      "pinned": "3.6.0",
       "track": "npm",
       "package": "@icp-sdk/canisters",
       "affects": "`@icp-sdk/canisters` APIs, notably `AssetManager` in references/application-canisters.md and guides/frontends/asset-canister.md, which states a minimum of 3.5.0. This repo's semver tags lag its published versions, so npm is the release signal. Changelog: https://github.com/dfinity/icp-js-canisters/blob/main/CHANGELOG.md",
@@ -90,7 +99,7 @@
     {
       "repo": "dfinity/icp-cli-recipes",
       "name": "asset-canister",
-      "pinned": "asset-canister-v2.2.1",
+      "pinned": "asset-canister-v2.3.0",
       "track": "release",
       "tagPattern": "^asset-canister-v\\d+\\.\\d+\\.\\d+$",
       "affects": "Cited in 10 places across docs/, including references/application-canisters.md and guides/frontends/asset-canister.md. The legacy frontend recipe; static-site supersedes it. Each recipe in this repo tags and releases on its own prefix, so it gets its own entry: a single pattern across prefixes would compare `rust-` against `static-site-` textually and only ever surface one of them.",
@@ -108,7 +117,7 @@
     {
       "repo": "dfinity/icp-cli-recipes",
       "name": "rust",
-      "pinned": "rust-v3.3.0",
+      "pinned": "rust-v3.4.0",
       "track": "release",
       "tagPattern": "^rust-v\\d+\\.\\d+\\.\\d+$",
       "affects": "Cited in 6 places as the Rust canister recipe in icp.yaml examples. Each recipe in this repo tags and releases on its own prefix, so it gets its own entry: a single pattern across prefixes would compare `rust-` against `static-site-` textually and only ever surface one of them.",
@@ -117,7 +126,7 @@
     {
       "repo": "dfinity/icp-cli-recipes",
       "name": "motoko",
-      "pinned": "motoko-v5.0.0",
+      "pinned": "motoko-v5.1.0",
       "track": "release",
       "tagPattern": "^motoko-v\\d+\\.\\d+\\.\\d+$",
       "affects": "Cited in 3 places as the Motoko canister recipe in icp.yaml examples. Each recipe in this repo tags and releases on its own prefix, so it gets its own entry: a single pattern across prefixes would compare `rust-` against `static-site-` textually and only ever surface one of them.",
@@ -126,7 +135,7 @@
     {
       "repo": "dfinity/icp-cli-recipes",
       "name": "prebuilt",
-      "pinned": "prebuilt-v2.0.0",
+      "pinned": "prebuilt-v2.1.0",
       "track": "release",
       "tagPattern": "^prebuilt-v\\d+\\.\\d+\\.\\d+$",
       "affects": "Cited once, in guides/canister-management/reproducible-builds.md. Each recipe in this repo tags and releases on its own prefix, so it gets its own entry: a single pattern across prefixes would compare `rust-` against `static-site-` textually and only ever surface one of them.",

AGENTS.md

@@ -229,9 +229,10 @@ git submodule update --init --depth 1   # do NOT use --recursive
 | Code examples (`snippet=`, `<CodeExample>`) | `.sources/examples/` |
 
 Pinned versions: [`.sources/VERSIONS`](.sources/VERSIONS). `motoko` and
-`internetidentity` are release-checked and synced by their own workflows;
-`examples` tracks a branch and is checked by the weekly **Upstream release
-check**. Canister IDs and code patterns are in the skills (see "Skills").
+`internetidentity` are release-checked and synced by their own workflows.
+`examples` is checked weekly, but reports only when a commit touches a file a
+`snippet=` quotes; the build already fails if such a path or `#region` marker
+stops resolving. Canister IDs and code patterns are in the skills (see "Skills").
 
 **Watched** are the repos where a release can silently invalidate a lot of what
 is published, so [`.sources/upstream.json`](.sources/upstream.json) records the

docs/getting-started/project-structure.mdx

@@ -87,7 +87,7 @@ The Motoko backend uses the `@dfinity/motoko` recipe, which compiles via `mops b
 ```yaml
 name: backend
 recipe:
-  type: "@dfinity/motoko@v5.0.0"
+  type: "@dfinity/motoko@v5.1.0"
 ```
 
 The recipe takes no source or Candid configuration. Instead, the source file (and optionally the Candid file and compiler flags) are declared in a `mops.toml` at the project root. The `[canisters]` key must match the canister `name`:
@@ -106,7 +106,7 @@ The Rust backend uses the `@dfinity/rust` recipe:
 ```yaml
 name: backend
 recipe:
-  type: "@dfinity/rust@v3.3.0"
+  type: "@dfinity/rust@v3.4.0"
   configuration:
     shrink: true
     candid: backend.did
@@ -123,7 +123,7 @@ The frontend uses the `@dfinity/asset-canister` recipe, which builds the fronten
 ```yaml
 name: frontend
 recipe:
-  type: "@dfinity/asset-canister@v2.2.1"
+  type: "@dfinity/asset-canister@v2.3.0"
   configuration:
     build:
       - npm install

docs/guides/canister-calls/candid.mdx

@@ -110,7 +110,7 @@ You can also provide a hand-written `.did` file by setting the `candid` field fo
 canisters:
   - name: backend
     recipe:
-      type: "@dfinity/motoko@v5.0.0"
+      type: "@dfinity/motoko@v5.1.0"
 ```
 
 Declare the source and Candid file under the canister's entry in `mops.toml`:
@@ -166,7 +166,7 @@ Reference the generated `.did` file in your `icp.yaml`:
 canisters:
   - name: my_canister
     recipe:
-      type: "@dfinity/rust@v3.3.0"
+      type: "@dfinity/rust@v3.4.0"
       configuration:
         candid: src/my_canister/my_canister.did
 ```

docs/guides/canister-calls/inter-canister-calls.mdx

@@ -201,7 +201,7 @@ Deployment order does not matter: `icp deploy` creates all canisters first, then
 **Init arguments.** Accept the target `Principal` as an `#[init]` argument and store it. This avoids the environment variable lookup at call time but requires passing the ID at every deploy and upgrade:
 
 ```bash
-TARGET_ID=$(icp canister id counter)
+TARGET_ID=$(icp canister status counter -i)
 icp deploy my_canister --argument "(principal \"$TARGET_ID\")"
 ```
 

docs/guides/canister-management/large-wasm.md

@@ -34,7 +34,7 @@ The Rust and prebuilt recipes expose a `compress` flag that gzip-compresses the
 canisters:
   - name: backend
     recipe:
-      type: "@dfinity/rust@v3.3.0"
+      type: "@dfinity/rust@v3.4.0"
       configuration:
         shrink: true
         compress: true

docs/guides/canister-management/logs.md

@@ -155,7 +155,7 @@ You can configure log visibility per canister in `icp.yaml` so it is applied on
 canisters:
   - name: backend
     recipe:
-      type: "@dfinity/rust@v3.3.0"
+      type: "@dfinity/rust@v3.4.0"
     settings:
       log_visibility: controllers   # "controllers" | "public" | allowed_viewers object
 ```

docs/guides/canister-management/optimization.md

@@ -26,7 +26,7 @@ This guide covers the main tools and techniques available:
 canisters:
   - name: backend
     recipe:
-      type: "@dfinity/rust@v3.3.0"
+      type: "@dfinity/rust@v3.4.0"
       configuration:
         shrink: true
 ```

docs/guides/canister-management/reproducible-builds.md

@@ -187,7 +187,7 @@ If you have already built a Wasm and computed its hash, you can deploy it using
 canisters:
   - name: my-canister
     recipe:
-      type: "@dfinity/prebuilt@v2.0.0"
+      type: "@dfinity/prebuilt@v2.1.0"
       configuration:
         path: dist/my-canister.wasm
         sha256: d7c1aba0de1d7152897aeca49bd5fe89a174b076a0ee1cc3b9e45fcf6bde71a6

docs/guides/chain-fusion/bitcoin.mdx

@@ -47,6 +47,7 @@ import Blob "mo:core/Blob";
 import Nat8 "mo:core/Nat8";
 import Array "mo:core/Array";
 import Runtime "mo:core/Runtime";
+import Nat "mo:core/Nat";
 
 persistent actor Self {
 
@@ -63,11 +64,11 @@ persistent actor Self {
     let bytes = Blob.toArray(Principal.toBlob(p));
     let size = bytes.size();
     let sub = Array.tabulate<Nat8>(32, func(i : Nat) : Nat8 {
-      if (i == 0) { Nat8.fromNat(size) }
+      if (i == 0) { Nat.toNat8(size) }
       else if (i <= size) { bytes[i - 1] }
       else { 0 }
     });
-    Blob.fromArray(sub)
+    Array.toBlob(sub)
   };
 
   public shared ({ caller }) func getDepositAddress() : async Text {

docs/guides/chain-fusion/chain-fusion-signer.md

@@ -14,7 +14,7 @@ The signer charges callers in cycles for each API call. You pre-approve the sign
 ## Prerequisites
 
 - An ICP identity with cycles in the [Cycles Ledger](../../references/system-canisters.md#cycles-ledger) (`um5iw-rqaaa-aaaaq-qaaba-cai`)
-- icp-cli installed and authenticated (`icp identity whoami`)
+- icp-cli installed and authenticated (`icp identity principal`)
 - For offline address derivation: Node.js and `npx`
 
 ## Approve payment

docs/guides/chain-fusion/ethereum.mdx

@@ -237,6 +237,7 @@ To read an ERC-20 balance, use `eth_call` with the `balanceOf(address)` function
 import EvmRpc "canister:evm_rpc";
 import Runtime "mo:core/Runtime";
 import Text "mo:core/Text";
+import Char "mo:core/Char";
 
 persistent actor {
 
@@ -290,7 +291,7 @@ persistent actor {
     switch (chars.next(), chars.next()) {
       case (?"0", ?"x") {
         var rest = "";
-        for (c in chars) { rest #= Text.fromChar(c) };
+        for (c in chars) { rest #= Char.toText(c) };
         rest;
       };
       case _ { hex };
@@ -593,7 +594,7 @@ Add the EVM RPC canister to your `icp.yaml` as a pre-built canister for local de
 canisters:
   - name: backend
     recipe:
-      type: "@dfinity/motoko@v5.0.0"
+      type: "@dfinity/motoko@v5.1.0"
   - name: evm_rpc
     build:
       steps:

docs/guides/chain-fusion/exchange-rates.mdx

@@ -24,6 +24,7 @@ In Motoko, declare the XRC actor interface inline and use the `(with cycles = am
 import Cycles "mo:core/Cycles";
 import Float "mo:core/Float";
 import Int "mo:core/Int";
+import Nat "mo:core/Nat";
 import Nat32 "mo:core/Nat32";
 import Nat64 "mo:core/Nat64";
 
@@ -93,8 +94,8 @@ persistent actor {
 
     switch result {
       case (#Ok rate) {
-        let scale = Float.fromInt(Int.pow(10, Nat32.toNat(rate.metadata.decimals)));
-        ?(Float.fromInt(Nat64.toNat(rate.rate)) / scale)
+        let scale = Int.toFloat(Int.pow(10, Nat32.toNat(rate.metadata.decimals)));
+        ?(Int.toFloat(Nat64.toNat(rate.rate)) / scale)
       };
       case (#Err err) {
         // handle specific errors as needed (see Error handling section below)
@@ -198,7 +199,7 @@ For reliability, use the start of the **previous minute** rather than the curren
 <TabItem label="Motoko">
 
 ```motoko
-let oneMinuteAgo : Nat64 = (Nat64.fromNat(Int.abs(Time.now())) / 1_000_000_000) - 60;
+let oneMinuteAgo : Nat64 = (Nat.toNat64(Int.abs(Time.now())) / 1_000_000_000) - 60;
 
 let request : GetExchangeRateRequest = {
   base_asset  = { symbol = "ICP"; class_ = #Cryptocurrency };