fix(links): add specific anchors to all internal and icp-cli doc links

AGENTS.md

@@ -143,6 +143,8 @@ git checkout main
 - Add `Co-Authored-By` or any AI attribution to commits or PR descriptions
 - Link to `internetcomputer.org/docs/` — that site is retired. For internal pages use relative paths, not absolute `docs.internetcomputer.org/...` URLs. Link to Learn Hub or explain inline for external content.
 - Link to internal pages that don't exist — every `[text](path.md)` must resolve to an actual file. Run `ls <target>` before linking. Links to `.mdx` pages use `.md` extension (Astro resolves both).
+- Link to a page without a section anchor when the surrounding context refers to a specific topic covered by a subsection — always check the target file's headings and include `#anchor` when a more precise destination exists. Verify anchors by grepping headings: `grep "^## \|^### " <target>`. Anchor slugs: lowercase, spaces → `-`, special chars stripped.
+- Link to `https://cli.internetcomputer.org/` (bare root) — all CLI doc pages are under a versioned path. Use `https://cli.internetcomputer.org/0.2/<path>` (current slug; verify with `cat .sources/icp-cli/docs-site/versions.json`) and confirm the path exists in `.sources/icp-cli/docs/<path>.md`. For command-specific links add a section anchor from `.sources/icp-cli/docs/reference/cli.md` (e.g. `#icp-canister-logs`, `#icp-canister-settings-update`, `#icp-cycles`). When bumping icp-cli to a new minor version, follow the "Link adaptation for `icp-cli`" checklist in "Bumping submodules".
 - Link externally when an internal page exists — check `docs/` before using an external URL
 - Offer, suggest, or perform PR reviews unless a human explicitly asks
 - Write em-dashes (`—`) or use `--` as an em-dash substitute in prose. These are banned in all content: body text, bullet descriptions, link label text (including "Next steps", "Further reading", and "See also" sections), and inline comments. Use a colon, semicolon, period, comma, or parentheses instead. (`--` is only acceptable inside fenced code blocks as a code comment or CLI flag.)
@@ -281,7 +283,7 @@ EOF
 | `motoko` | **Automated** — `.github/workflows/sync-motoko.yml` opens a PR with the submodule bump, synced docs, and VERSIONS update already committed. Review the content diff and merge. Also check for changed/removed API signatures — grep all Motoko code blocks in docs. |
 | `motoko-core` | Check for changed/removed API signatures — grep all Motoko code blocks in docs |
 | `cdk-rs` | Check `ic-cdk`, `ic-cdk-timers`, `ic-cdk-macros` API changes — grep all Rust code blocks |
-| `icp-cli` | Check for changed/removed commands or flags — grep all CLI examples |
+| `icp-cli` | Check for changed/removed commands or flags — grep all CLI examples. If the release tag introduces a new minor version (e.g. `v0.3.x`), update all CLI doc link slugs — see "Link adaptation for `icp-cli`" below |
 | `icskills` | Check for changed canister IDs or code patterns |
 | `examples` | Verify linked files still exist at the same path |
 | `icp-cli-recipes` | Check for renamed or removed recipes referenced in docs |
@@ -295,6 +297,26 @@ EOF
 | `papi` | Check for changed payment interface or cycle cost model |
 | `ic-pub-key` | Check for changed CLI flags or commands |
 
+**Link adaptation for `icp-cli`:** All links to the CLI docs site use a versioned path slug (e.g. `https://cli.internetcomputer.org/0.2/...`). The slug must match the current latest release. When the submodule is bumped to a new minor version:
+
+1. Read the new slug from the submodule: `cat .sources/icp-cli/docs-site/versions.json` — use the `"version"` value marked `"latest": true`.
+2. Extract every unique path currently linked and verify each one still exists in the new submodule **before** doing any replacements:
+   ```bash
+   grep -roh "cli\.internetcomputer\.org/[0-9][.0-9]*/[^\"' )#]*" docs/ --include="*.md" --include="*.mdx" \
+     | sed 's|cli\.internetcomputer\.org/[0-9][.0-9]*/||' | sort -u | grep -v "^$" \
+     | while read p; do
+         [ -f ".sources/icp-cli/docs/${p}.md" ] || echo "MISSING: $p"
+       done
+   ```
+   If any path is reported as MISSING, find its replacement in `.sources/icp-cli/docs/` and update that link manually. Do not proceed to step 3 until all paths are accounted for.
+3. Replace the old slug with the new one across all files:
+   ```bash
+   old=0.2   # replace with the old slug
+   new=0.3   # replace with the new slug
+   find docs/ \( -name "*.md" -o -name "*.mdx" \) | xargs sed -i "s|cli.internetcomputer.org/${old}/|cli.internetcomputer.org/${new}/|g"
+   ```
+4. Run `npm run build` to confirm no broken links.
+
 **Link adaptation for `internet-identity-spec.md`:** The upstream source (`docs/ii-spec.mdx`) uses absolute `internetcomputer.org` URLs pointing to the IC interface spec. Our file uses relative paths into the split `ic-interface-spec/` directory. After every re-sync, run:
 ```bash
 grep -n "ic-interface-spec" docs/references/internet-identity-spec.md

docs/concepts/app-architecture.md

@@ -71,7 +71,7 @@ For maximum throughput, distribute canisters across multiple [subnets](network-o
 
 ## Data storage
 
-Canisters store data in heap memory during execution and can persist data across upgrades using [stable memory](../guides/backends/data-persistence.md): there is no external database. Libraries provide familiar data-structure abstractions on top of raw stable memory:
+Canisters store data in heap memory during execution and can persist data across upgrades using [stable memory](../guides/backends/data-persistence.md#store-data-durably): there is no external database. Libraries provide familiar data-structure abstractions on top of raw stable memory:
 
 - **Motoko:** the [`core` standard library](https://mops.one/core/docs) includes persistent data structures designed for upgrade-safe storage.
 - **Rust:** [`ic-stable-structures`](https://docs.rs/ic-stable-structures/latest/ic_stable_structures/) provides `StableBTreeMap` and other structures for stable memory.

docs/concepts/canisters.md

@@ -62,7 +62,7 @@ Each canister has two storage regions:
 
 **Heap memory** is standard Wasm linear memory. It holds your program's heap-allocated data: variables, data structures, and anything your code allocates at runtime. Both 32-bit and 64-bit Wasm memory are supported. Heap memory is cleared when you upgrade the canister's Wasm module.
 
-**Stable memory** is a separate address space accessed through the [system API](../references/ic-interface-spec/canister-interface.md). It survives upgrades, making it the right place for any data that must persist long-term. Libraries like `StableBTreeMap` (Rust) or the [`core`](https://mops.one/core/docs) persistent data structures (Motoko) let you work with stable memory through familiar abstractions.
+**Stable memory** is a separate address space accessed through the [system API](../references/ic-interface-spec/canister-interface.md#system-api-stable-memory). It survives upgrades, making it the right place for any data that must persist long-term. Libraries like `StableBTreeMap` (Rust) or the [`core`](https://mops.one/core/docs) persistent data structures (Motoko) let you work with stable memory through familiar abstractions.
 
 After a message executes successfully, the system atomically commits all memory changes. If execution traps (fails), no changes are committed. The canister's state rolls back to what it was before that message.
 

docs/concepts/chain-key-cryptography.md

@@ -52,7 +52,7 @@ Each scheme is backed by a pair of management canister methods:
 - **Public key retrieval** (`ecdsa_public_key`, `schnorr_public_key`): returns a canister's public key for a given derivation path.
 - **Signing** (`sign_with_ecdsa`, `sign_with_schnorr`): computes a threshold signature using the canister's derived key.
 
-See the [Management canister reference](../references/management-canister.md) for the full API, and the [IC interface specification](../references/ic-interface-spec/index.md) for the authoritative protocol-level details.
+See the [Management canister reference](../references/management-canister.md#chain-key-signing) for the full API, and the [IC interface specification](../references/ic-interface-spec/index.md) for the authoritative protocol-level details.
 
 ### Key derivation
 

docs/concepts/security.md

@@ -61,7 +61,7 @@ The following threats are your responsibility to mitigate:
 
 Every update method is publicly callable. If you do not check the caller, anyone can invoke admin functions, drain funds, or corrupt state. The anonymous principal (`2vxsx-fae`) is a particularly common gap: it must be explicitly rejected in any authenticated endpoint, because otherwise it acts as a shared identity that anyone can use.
 
-See [Access management](../guides/security/access-management.md) for implementation patterns.
+See [Access management](../guides/security/access-management.md#reject-anonymous-callers) for implementation patterns.
 
 ### Reentrancy and async interleaving
 

docs/concepts/timers.md

@@ -93,6 +93,6 @@ Timers introduce two security-relevant properties developers should understand:
 
 - [Timers guide](../guides/backends/timers.md): practical API usage for Rust and Motoko
 - [Canisters](canisters.md): the canister execution model
-- [IC interface specification](../references/ic-interface-spec/index.md): the protocol-level timer definition
+- [IC interface specification](../references/ic-interface-spec/canister-interface.md#global-timer): the protocol-level timer definition
 
 <!-- Upstream: informed by dfinity/portal docs/building-apps/network-features/periodic-tasks-timers.mdx, dfinity/cdk-rs ic-cdk-timers/src/lib.rs, caffeinelabs/motoko doc/md/core/Timer.md -->

docs/getting-started/project-structure.mdx

@@ -72,7 +72,7 @@ Beyond canisters, `icp.yaml` can also define **networks** (where to deploy) and
 | `local` | `local` (managed, localhost:8000) | Local development |
 | `ic` | `ic` (connected, https://icp-api.io) | Mainnet production |
 
-You only need to add custom networks or environments when you have staging environments, testnets, or other deployment targets. See the [icp-cli configuration reference](https://cli.internetcomputer.org/) for the full schema.
+You only need to add custom networks or environments when you have staging environments, testnets, or other deployment targets. See the [icp-cli configuration reference](https://cli.internetcomputer.org/0.2/reference/configuration#networks) for the full schema.
 
 ## Canister configuration (canister.yaml)
 
@@ -147,7 +147,7 @@ icp project show
 
 This outputs the effective configuration, including all expanded recipe steps and implicit defaults.
 
-Recipes are Handlebars templates hosted at [dfinity/icp-cli-recipes](https://github.com/dfinity/icp-cli-recipes). You can also create local or remote recipes for custom build patterns. See the [icp-cli recipes documentation](https://cli.internetcomputer.org/) for details.
+Recipes are Handlebars templates hosted at [dfinity/icp-cli-recipes](https://github.com/dfinity/icp-cli-recipes). You can also create local or remote recipes for custom build patterns. See the [icp-cli recipes documentation](https://cli.internetcomputer.org/0.2/guides/creating-recipes) for details.
 
 ## The .icp/ directory
 
@@ -238,14 +238,14 @@ Bindings are generated TypeScript (or Rust) code that provides type-safe access
 
 In the hello-world template, the frontend's build step runs `npm run generate --prefix app`, which uses `@icp-sdk/bindgen` to generate TypeScript bindings from the backend's `backend.did` file.
 
-For a deep dive on binding generation, see [Binding generation](../guides/canister-calls/binding-generation.md).
+For a deep dive on binding generation, see [Binding generation](../guides/canister-calls/candid.md#binding-generation).
 
 ## Next steps
 
 - [What next?](choose-your-path.md): pick a development path based on what you want to build
-- [Binding generation](../guides/canister-calls/binding-generation.md): deep dive on generating type-safe client code
+- [Binding generation](../guides/canister-calls/candid.md#binding-generation): deep dive on generating type-safe client code
 - [Asset canister](../guides/frontends/asset-canister.md): how the frontend recipe and asset upload work
 - [Canister lifecycle](../guides/canister-management/lifecycle.md): build, deploy, upgrade, and manage canisters
-- [icp-cli reference](https://cli.internetcomputer.org/): full CLI and configuration documentation
+- [icp-cli reference](https://cli.internetcomputer.org/0.2/reference/cli): full CLI and configuration documentation
 
 {/* Upstream: informed by dfinity/icp-cli docs/concepts/project-model.md, docs/concepts/recipes.md, docs/concepts/binding-generation.md, docs/concepts/canister-discovery.md */}

docs/getting-started/quickstart.md

@@ -37,7 +37,7 @@ icp --version
 ic-wasm --version
 ```
 
-> **Alternative methods:** [Homebrew, shell scripts, and other options](https://cli.internetcomputer.org/guides/installation/) are also available.
+> **Alternative methods:** [Homebrew, shell scripts, and other options](https://cli.internetcomputer.org/0.2/guides/installation) are also available.
 
 ## Create a project
 
@@ -130,6 +130,6 @@ Each canister name maps to a directory containing its own `canister.yaml` with b
 - [Choose your path](choose-your-path.md): pick a development path based on what you want to build
 - [Concepts: Canisters](../concepts/canisters.md): learn what canisters are and how they work
 - [AI coding agents](../guides/ai-coding-agents.md): use ICP skills to build on the Internet Computer with AI
-- [icp-cli documentation](https://cli.internetcomputer.org/): full CLI reference and guides
+- [icp-cli documentation](https://cli.internetcomputer.org/0.2/): full CLI reference and guides
 
 <!-- Upstream: informed by dfinity/icp-cli docs/quickstart.md, docs/tutorial.md -->

docs/guides/authentication/verifiable-credentials.md

@@ -49,7 +49,7 @@ The relying party and Internet Identity communicate through [`window.postMessage
 }
 ```
 
-The relying party then sends a `request_credential` message (see [Relying party](#requesting-a-credential) below).
+The relying party then sends a `request_credential` message (see [Relying party](#implementing-a-relying-party) below).
 
 ## Implementing an issuer
 

docs/guides/backends/data-persistence.mdx

@@ -574,7 +574,7 @@ If the count drops to 0 after upgrade, the data is not in stable memory. Review
 ## Related
 
 - [Orthogonal Persistence](../../concepts/orthogonal-persistence.md): conceptual explanation of heap vs. stable memory
-- [Canister Lifecycle](../canister-management/lifecycle.md): upgrade hooks and canister lifecycle
+- [Canister Lifecycle](../canister-management/lifecycle.md#what-happens-during-an-upgrade): upgrade hooks and canister lifecycle
 - [Stable Structures (Rust)](../../languages/rust/stable-structures.md): deep dive into `ic-stable-structures`
 - [Motoko](../../languages/motoko/index.md): Motoko language overview and persistence model
 

docs/guides/backends/https-outcalls.mdx

@@ -146,7 +146,7 @@ For reference, on a 13-node subnet:
 - Per request byte: 5,200 cycles
 - Per `max_response_bytes` byte: 10,400 cycles
 
-See [Cycles Costs](../../references/cycles-costs.md) for the full pricing table.
+See [Cycles Costs](../../references/cycles-costs.md#https-outcalls) for the full pricing table.
 
 ## Limitations and pitfalls
 
@@ -166,6 +166,6 @@ Use the "Full example in ICP Ninja" links above to deploy and test directly in t
 - [Management canister reference](../../references/management-canister.md#http_request): full `http_request` parameter reference including all fields
 - [Exchange Rate Canister (XRC)](https://github.com/dfinity/exchange-rate-canister): a production service powered by HTTPS outcalls that fetches digital asset and fiat exchange rates
 - [Chain Fusion: Ethereum](../chain-fusion/ethereum.md): the EVM RPC canister uses HTTPS outcalls under the hood
-- [Cycles Costs](../../references/cycles-costs.md): outcall pricing details
+- [Cycles Costs](../../references/cycles-costs.md#https-outcalls): outcall pricing details
 
 {/* Upstream: informed by dfinity/portal docs/building-apps/network-features/using-http/https-outcalls/; dfinity/examples send_http_get, send_http_post */}

docs/guides/backends/randomness.md

@@ -226,6 +226,6 @@ Note: this example predates `mo:core` and uses the older `Random.Finite` API. Th
 - [Verifiable Randomness (concept)](../../concepts/verifiable-randomness.md): how the IC's threshold VRF works
 - [Management Canister](../../references/management-canister.md): `raw_rand` API reference
 - [Data Integrity](../security/data-integrity.md): using randomness in a secure application design
-- [Inter-canister calls](../canister-calls/inter-canister-calls.md): async patterns and reentrancy
+- [Inter-canister calls](../canister-calls/inter-canister-calls.md#reentrancy): async patterns and reentrancy
 
 <!-- Upstream: informed by dfinity/portal — docs/building-apps/integrations/randomness.mdx; dfinity/icskills — skills/canister-security/SKILL.md; dfinity/examples — motoko/random_maze; caffeinelabs/motoko-core — src/Random.mo -->

docs/guides/backends/timers.mdx

@@ -163,7 +163,7 @@ fn init() {
 }
 ```
 
-See [Canister lifecycle](../canister-management/lifecycle.md) for init and upgrade hook details.
+See [Canister lifecycle](../canister-management/lifecycle.md#what-happens-during-an-upgrade) for init and upgrade hook details.
 
 ## Timers after upgrades
 
@@ -215,7 +215,7 @@ Timer tasks are added to the canister's input queue. If the canister or subnet i
 
 The canister output queue is limited to 500 messages. This caps how many timers can fire in a single round. The CDK also enforces internal rate limits (250 concurrent timer calls globally, 5 per interval timer).
 
-See [Cycles and costs](../../references/cycles-costs.md) for current pricing.
+See [Cycles and costs](../../references/cycles-costs.md#cost-table) for current pricing.
 
 ## Heartbeats (legacy)
 
@@ -243,7 +243,7 @@ The CDK timers library (`ic-cdk-timers` for Rust, `mo:core/Timer` for Motoko) bu
 3. In `canister_global_timer`, runs each expired task as a self-canister call to isolate tasks from each other and from the library code
 4. Reschedules recurring tasks at the end of their execution
 
-For protocol internals, see [Timers](../../concepts/timers.md) and the [IC interface specification](../../references/ic-interface-spec/index.md).
+For protocol internals, see [Timers](../../concepts/timers.md) and the [IC interface specification](../../references/ic-interface-spec/canister-interface.md#global-timer).
 
 ## Frequently asked questions
 
@@ -277,8 +277,8 @@ For a complete working example with cycle tracking and multiple timers:
 
 ## Next steps
 
-- [Canister lifecycle](../canister-management/lifecycle.md): init, pre/post-upgrade hooks
+- [Canister lifecycle](../canister-management/lifecycle.md#what-happens-during-an-upgrade): init, pre/post-upgrade hooks
 - [Timers (concept)](../../concepts/timers.md): how the IC protocol timer works
-- [Cycles and costs](../../references/cycles-costs.md): current pricing
+- [Cycles and costs](../../references/cycles-costs.md#cost-table): current pricing
 
 {/* Upstream: informed by dfinity/portal docs/building-apps/network-features/periodic-tasks-timers.mdx, docs/building-apps/network-features/time-and-timestamps.mdx, dfinity/cdk-rs ic-cdk-timers/src/lib.rs, and caffeinelabs/motoko-core src/Timer.mo */}

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

@@ -16,13 +16,13 @@ Parallel calls are most beneficial when the caller and callee are on **different
 <Tabs syncKey="lang">
 <TabItem label="Motoko">
 
-- [icp-cli](https://cli.internetcomputer.org/) installed
+- [icp-cli](https://cli.internetcomputer.org/0.2/guides/installation) installed
 - `mops` package manager with `core = "2.0.0"` in `mops.toml`
 
 </TabItem>
 <TabItem label="Rust">
 
-- [icp-cli](https://cli.internetcomputer.org/) installed
+- [icp-cli](https://cli.internetcomputer.org/0.2/guides/installation) installed
 - `ic-cdk = "0.19"` and `futures = "0.3"` in `Cargo.toml`
 
 </TabItem>