From 0745a3982b1a24cdd6f8b8c50e51a13f94a27871 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Tue, 5 May 2026 10:36:24 +0200 Subject: [PATCH 1/3] fix(links): add specific anchors to all internal and icp-cli doc links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fixes 2 broken file links (binding-generation.md → candid.md#binding-generation) - Fixes 5 wrong anchors (candid-spec.md stale portal anchors, digital-asset-standards.md) - Adds section anchors to ~35 links that pointed to page tops (cycles-costs.md, inter-canister-calls.mdx, management-canister.md, lifecycle guides, etc.) - Upgrades all cli.internetcomputer.org links from bare root to versioned paths (/0.2/) with specific page paths and per-command anchors where applicable - Fixes issue #191: vetkd_encrypted_key → vetkd_derive_key, ic_ → ic- prefix typos in management-canister.md, #canister-ids → chain-key-canister-ids.md, #requesting-a-credential → #implementing-a-relying-party, XDR → glossary.md#xdr - Adds CLAUDE.md rules requiring specific anchors and versioned CLI doc paths so future agents don't reintroduce generic root links --- AGENTS.md | 2 ++ docs/concepts/app-architecture.md | 2 +- docs/concepts/canisters.md | 2 +- docs/concepts/chain-key-cryptography.md | 2 +- docs/concepts/security.md | 2 +- docs/concepts/timers.md | 2 +- docs/getting-started/project-structure.mdx | 10 +++++----- docs/getting-started/quickstart.md | 4 ++-- .../authentication/verifiable-credentials.md | 2 +- docs/guides/backends/data-persistence.mdx | 2 +- docs/guides/backends/https-outcalls.mdx | 4 ++-- docs/guides/backends/randomness.md | 2 +- docs/guides/backends/timers.mdx | 10 +++++----- .../parallel-inter-canister-calls.mdx | 4 ++-- .../canister-management/cycles-management.mdx | 8 ++++---- docs/guides/canister-management/logs.md | 3 ++- docs/guides/canister-management/settings.mdx | 8 ++++---- docs/guides/canister-management/snapshots.md | 2 +- .../canister-management/subnet-selection.md | 4 ++-- docs/guides/digital-assets/chain-key-tokens.mdx | 2 +- docs/guides/digital-assets/ledgers.mdx | 2 +- docs/guides/frontends/frameworks.md | 4 ++-- docs/guides/security/access-management.mdx | 2 +- docs/guides/security/canister-upgrades.md | 4 ++-- docs/guides/security/dos-prevention.md | 8 ++++---- docs/guides/security/inter-canister-calls.md | 2 +- docs/guides/testing/pocket-ic.md | 2 +- docs/guides/testing/strategies.md | 2 +- docs/index.mdx | 2 +- docs/references/candid-spec.md | 14 +++++++------- docs/references/cycles-costs.md | 2 +- docs/references/developer-tools.md | 4 ++-- docs/references/digital-asset-standards.md | 2 +- docs/references/execution-errors.md | 16 ++++++++-------- .../ic-interface-spec/canister-interface.md | 2 +- .../ic-interface-spec/management-canister.md | 6 +++--- 36 files changed, 77 insertions(+), 74 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index de9a9201..2468fda0 100644 --- a/AGENTS.md +++ b/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 ` 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 "^## \|^### " `. 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/` and verify the path exists in `.sources/icp-cli/docs/.md`. For command-specific links, add a section anchor derived from the heading in `.sources/icp-cli/docs/reference/cli.md` (e.g. `#icp-canister-logs`, `#icp-canister-settings-update`, `#icp-cycles`). When the icp-cli version is bumped, update the version prefix in all CLI doc links. - 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.) diff --git a/docs/concepts/app-architecture.md b/docs/concepts/app-architecture.md index 56fa1f12..868e6c67 100644 --- a/docs/concepts/app-architecture.md +++ b/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. diff --git a/docs/concepts/canisters.md b/docs/concepts/canisters.md index aaa369c8..cdbe6c46 100644 --- a/docs/concepts/canisters.md +++ b/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. diff --git a/docs/concepts/chain-key-cryptography.md b/docs/concepts/chain-key-cryptography.md index 5f4370be..bcc916dd 100644 --- a/docs/concepts/chain-key-cryptography.md +++ b/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 diff --git a/docs/concepts/security.md b/docs/concepts/security.md index f1d8dbe9..ef23dff7 100644 --- a/docs/concepts/security.md +++ b/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 diff --git a/docs/concepts/timers.md b/docs/concepts/timers.md index 0e9d887b..e78c7b2d 100644 --- a/docs/concepts/timers.md +++ b/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 diff --git a/docs/getting-started/project-structure.mdx b/docs/getting-started/project-structure.mdx index dc22431f..611846c1 100644 --- a/docs/getting-started/project-structure.mdx +++ b/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 */} diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 2262ece4..204e2afa 100644 --- a/docs/getting-started/quickstart.md +++ b/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 diff --git a/docs/guides/authentication/verifiable-credentials.md b/docs/guides/authentication/verifiable-credentials.md index 8951a2d0..f41894a0 100644 --- a/docs/guides/authentication/verifiable-credentials.md +++ b/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 diff --git a/docs/guides/backends/data-persistence.mdx b/docs/guides/backends/data-persistence.mdx index c6727ef5..564edc8d 100644 --- a/docs/guides/backends/data-persistence.mdx +++ b/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 diff --git a/docs/guides/backends/https-outcalls.mdx b/docs/guides/backends/https-outcalls.mdx index e0f9c48d..971ed7ce 100644 --- a/docs/guides/backends/https-outcalls.mdx +++ b/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 */} diff --git a/docs/guides/backends/randomness.md b/docs/guides/backends/randomness.md index 6d3b101d..ec94e8f3 100644 --- a/docs/guides/backends/randomness.md +++ b/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 diff --git a/docs/guides/backends/timers.mdx b/docs/guides/backends/timers.mdx index 0c9b8a27..cf15f6d6 100644 --- a/docs/guides/backends/timers.mdx +++ b/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 */} diff --git a/docs/guides/canister-calls/parallel-inter-canister-calls.mdx b/docs/guides/canister-calls/parallel-inter-canister-calls.mdx index 03cf3320..c1ed2fc6 100644 --- a/docs/guides/canister-calls/parallel-inter-canister-calls.mdx +++ b/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 -- [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` -- [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` diff --git a/docs/guides/canister-management/cycles-management.mdx b/docs/guides/canister-management/cycles-management.mdx index 3b855094..71821bc3 100644 --- a/docs/guides/canister-management/cycles-management.mdx +++ b/docs/guides/canister-management/cycles-management.mdx @@ -57,7 +57,7 @@ icp cycles balance -n ic # Output: ~5T cycles ``` -**Budget guidance:** Plan for 1–2T cycles per canister as a starting balance. A simple backend canister with moderate traffic costs roughly 0.1–0.5T cycles per month, though this varies with storage and call volume. See the [cycles costs reference](../../references/cycles-costs.md) for per-operation pricing. +**Budget guidance:** Plan for 1–2T cycles per canister as a starting balance. A simple backend canister with moderate traffic costs roughly 0.1–0.5T cycles per month, though this varies with storage and call volume. See the [cycles costs reference](../../references/cycles-costs.md#cost-table) for per-operation pricing. ## Checking canister cycle balances @@ -348,7 +348,7 @@ icp deploy -e staging icp deploy -e production ``` -Each environment maintains separate canister IDs. Mainnet IDs are stored in `.icp/data/mappings/.ids.json` and should be committed to version control. See [Managing environments](https://cli.internetcomputer.org/) for full configuration options. +Each environment maintains separate canister IDs. Mainnet IDs are stored in `.icp/data/mappings/.ids.json` and should be committed to version control. See [Managing environments](https://cli.internetcomputer.org/0.2/guides/managing-environments) for full configuration options. ## Production deployment checklist @@ -411,9 +411,9 @@ icp canister top-up backend --amount 1T -n ic - [Canister settings](settings.md): Freezing threshold, memory allocation, compute allocation - [Canister lifecycle](lifecycle.md): Create, install, upgrade, and delete canisters -- [Cycles costs reference](../../references/cycles-costs.md): Exact cost tables per operation +- [Cycles costs reference](../../references/cycles-costs.md#cost-table): Exact cost tables per operation - [Cycles](../../concepts/cycles.md): Why canisters pay for execution - [Reproducible builds](reproducible-builds.md): Verify your WASM is trustworthy before deploying -- [icp-cli docs](https://cli.internetcomputer.org/): Full command reference +- [icp-cli docs](https://cli.internetcomputer.org/0.2/reference/cli#icp-cycles): Full command reference for `icp cycles` and `icp canister top-up` {/* Upstream: informed by dfinity/portal (docs/building-apps/canister-management/topping-up.mdx, docs/building-apps/getting-started/tokens-and-cycles.mdx; dfinity/icp-cli) docs/guides/deploying-to-mainnet.md, docs/guides/tokens-and-cycles.md, docs/guides/managing-environments.md; dfinity/icskills: skills/cycles-management/SKILL.md */} diff --git a/docs/guides/canister-management/logs.md b/docs/guides/canister-management/logs.md index 242dd5cd..1b24b691 100644 --- a/docs/guides/canister-management/logs.md +++ b/docs/guides/canister-management/logs.md @@ -405,6 +405,7 @@ async fn main() -> Result<()> { - [Canister lifecycle](lifecycle.md): configure log visibility and memory limits when creating or deploying a canister - [Testing strategies](../testing/strategies.md): use canister logs as part of your debugging workflow -- [CLI reference](https://cli.internetcomputer.org/): full documentation for `icp canister logs` and `icp canister settings update` +- [CLI reference: `icp canister logs`](https://cli.internetcomputer.org/0.2/reference/cli#icp-canister-logs): full command flags and options +- [CLI reference: `icp canister settings update`](https://cli.internetcomputer.org/0.2/reference/cli#icp-canister-settings-update): full command flags and options diff --git a/docs/guides/canister-management/settings.mdx b/docs/guides/canister-management/settings.mdx index aafca420..d1adaed5 100644 --- a/docs/guides/canister-management/settings.mdx +++ b/docs/guides/canister-management/settings.mdx @@ -69,7 +69,7 @@ settings: A value of `50` means the canister gets 50% of an execution core and is scheduled at least every other round. A value of `100` means the canister runs every round. -Compute allocation incurs a rental fee based on time and allocation percentage, regardless of whether the canister actually executes. This increases idle [cycle](../../concepts/cycles.md) consumption. See [cycles costs](../../references/cycles-costs.md) for pricing details. +Compute allocation incurs a rental fee based on time and allocation percentage, regardless of whether the canister actually executes. This increases idle [cycle](../../concepts/cycles.md) consumption. See [cycles costs](../../references/cycles-costs.md#compute-allocation) for pricing details. ### Memory allocation @@ -90,7 +90,7 @@ Supported suffixes: `kb` (1,000), `kib` (1,024), `mb` (1,000,000), `mib` (1,048, When set, the canister draws new Wasm and stable memory from the pre-allocated pool. If usage exceeds the allocation, additional memory is allocated on demand and may fail if the subnet is at capacity. -Like compute allocation, memory allocation incurs a rental fee based on time and allocated amount, regardless of actual usage. See [cycles costs](../../references/cycles-costs.md) for pricing. +Like compute allocation, memory allocation incurs a rental fee based on time and allocated amount, regardless of actual usage. See [cycles costs](../../references/cycles-costs.md#storage-reservation) for pricing. ### Freezing threshold @@ -332,7 +332,7 @@ icp canister settings update backend -e ic --freezing-threshold 90d Additional flags: `--reserved-cycles-limit`, `--wasm-memory-threshold`, `--log-memory-limit`, `--add-environment-variable`. Run `icp canister settings update --help` for the full list. -For the full list of CLI flags, see the [icp-cli reference](https://cli.internetcomputer.org/). +For the full list of CLI flags, see the [icp-cli reference](https://cli.internetcomputer.org/0.2/reference/cli#icp-canister-settings-update). ## Updating settings programmatically @@ -454,7 +454,7 @@ How you configure controllers depends on the trust model for your canister: - [Canister lifecycle](lifecycle.md): Create, deploy, upgrade, stop, and delete canisters. - [Cycles management](cycles-management.md): Monitor and top up cycle balances. -- [Cycles costs reference](../../references/cycles-costs.md): Pricing for compute and memory allocation. +- [Cycles costs reference](../../references/cycles-costs.md#compute-allocation): Pricing for compute and memory allocation. - [Management canister reference](../../references/management-canister.md): Full interface specification. {/* Upstream: informed by dfinity/portal (docs/building-apps/canister-management/settings.mdx, docs/building-apps/canister-management/control.mdx, docs/references/_attachments/ic.did (snapshot_visibility field); dfinity/icp-cli) docs/reference/canister-settings.md, docs/reference/cli.md; dfinity/icskills: skills/cycles-management/SKILL.md */} diff --git a/docs/guides/canister-management/snapshots.md b/docs/guides/canister-management/snapshots.md index 7e10d1b4..828f90c1 100644 --- a/docs/guides/canister-management/snapshots.md +++ b/docs/guides/canister-management/snapshots.md @@ -180,6 +180,6 @@ icp canister status my-canister -e ic - [Canister lifecycle](lifecycle.md): Understand how snapshots fit into the upgrade workflow - [Canister upgrades security](../security/canister-upgrades.md): Security considerations when using snapshot-based rollbacks -- [icp-cli canister snapshot reference](https://cli.internetcomputer.org/): Full command reference for all snapshot subcommands +- [icp-cli canister snapshot reference](https://cli.internetcomputer.org/0.2/guides/canister-snapshots): Full command reference for all snapshot subcommands diff --git a/docs/guides/canister-management/subnet-selection.md b/docs/guides/canister-management/subnet-selection.md index 00629097..e17c33a2 100644 --- a/docs/guides/canister-management/subnet-selection.md +++ b/docs/guides/canister-management/subnet-selection.md @@ -100,7 +100,7 @@ Subnets enforce a storage reservation policy above 750 GiB of total utilization. If you expect your canister to use significant storage, check the current utilization of candidate subnets on the [ICP Dashboard](https://dashboard.internetcomputer.org/subnets) before deploying. Choosing a subnet with available headroom avoids unexpected reservation costs as your canister grows. -For details on storage costs and the reservation formula, see [Cycles costs](../../references/cycles-costs.md). +For details on storage costs and the reservation formula, see [Cycles costs](../../references/cycles-costs.md#storage-reservation). ## Troubleshooting @@ -119,7 +119,7 @@ Note that any canister ID change means losing access to any threshold signature ## Next steps -- [Cycles costs](../../references/cycles-costs.md): Cost tables and the subnet multiplier formula +- [Cycles costs](../../references/cycles-costs.md#replication-factors): Cost tables and the subnet multiplier formula - [Subnet types reference](../../references/subnet-types.md): Full reference for all subnet types with node counts and properties - [Canister snapshots](snapshots.md): Transfer state between canisters when migrating subnets - [Network overview](../../concepts/network-overview.md): How subnets fit into the ICP architecture diff --git a/docs/guides/digital-assets/chain-key-tokens.mdx b/docs/guides/digital-assets/chain-key-tokens.mdx index 673bc1af..791f85ff 100644 --- a/docs/guides/digital-assets/chain-key-tokens.mdx +++ b/docs/guides/digital-assets/chain-key-tokens.mdx @@ -17,7 +17,7 @@ For plain ICRC-1/ICRC-2 transfers without the minting/withdrawal flows, see [Led ## Available chain-key assets -The current chain-key assets are: **ckBTC** (Bitcoin), **ckETH** (Ether), **ckERC20** (ERC-20 tokens including ckUSDC, ckUSDT, ckLINK, and others), **ckDOGE** (Dogecoin), and **ckSOL** (Solana). Transfer code is identical across all of them: only the canister ID and fee denomination differ. See [Canister IDs](#canister-ids) for the full list. +The current chain-key assets are: **ckBTC** (Bitcoin), **ckETH** (Ether), **ckERC20** (ERC-20 tokens including ckUSDC, ckUSDT, ckLINK, and others), **ckDOGE** (Dogecoin), and **ckSOL** (Solana). Transfer code is identical across all of them: only the canister ID and fee denomination differ. See [Canister IDs](../../references/chain-key-canister-ids.md) for the full list. If you need direct Bitcoin UTXO access or custom Bitcoin transaction signing, see [Bitcoin integration](../chain-fusion/bitcoin.md). If you need to call Ethereum contracts or interact with Ethereum infrastructure directly, see [Ethereum integration](../chain-fusion/ethereum.md). For fast ICP-native transfers, chain-key tokens are the simpler choice. diff --git a/docs/guides/digital-assets/ledgers.mdx b/docs/guides/digital-assets/ledgers.mdx index 085bcb9e..18e26ab4 100644 --- a/docs/guides/digital-assets/ledgers.mdx +++ b/docs/guides/digital-assets/ledgers.mdx @@ -582,6 +582,6 @@ icp canister call icrc1_ledger icrc1_transfer \ - [Chain-key tokens](chain-key-tokens.md): minting, depositing, and withdrawing ckBTC, ckETH, ckDOGE, and ckSOL - [Rosetta API](rosetta.md): client-side indexing and transaction construction for exchanges and custody platforms - [Wallet integration](wallet-integration.md): connecting wallets to your app -- [Inter-canister calls](../canister-calls/inter-canister-calls.md): how canister-to-canister calls work, for example when the index canister reads blocks from the ledger +- [Inter-canister calls](../canister-calls/inter-canister-calls.md#making-calls): how canister-to-canister calls work, for example when the index canister reads blocks from the ledger {/* Upstream: informed by dfinity/portal docs/defi/token-standards/, docs/defi/token-integrations/: icrc-1.mdx, icrc-2.mdx, icrc-7.mdx, icrc-37.mdx; dfinity/portal docs/defi/token-indexes/index.mdx (index canister / get_account_transactions); dfinity/portal docs/defi/rosetta/icrc_rosetta/index.mdx (ICRC Rosetta); dfinity/icskills skills/icrc-ledger/SKILL.md */} diff --git a/docs/guides/frontends/frameworks.md b/docs/guides/frontends/frameworks.md index 9fd36d95..06605c91 100644 --- a/docs/guides/frontends/frameworks.md +++ b/docs/guides/frontends/frameworks.md @@ -11,7 +11,7 @@ This guide shows you how to configure your framework's build pipeline, wire up t ## Prerequisites -- [icp-cli](https://cli.internetcomputer.org/) installed: `npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm` +- [icp-cli](https://cli.internetcomputer.org/0.2/guides/installation) installed: `npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm` - A backend canister deployed (or a static-only site with no backend) - Familiarity with [asset canisters](asset-canister.md) @@ -182,7 +182,7 @@ If your Vue app calls `getCanisterEnv()` to read canister IDs, add the same `ser ## Authentication -Authentication with Internet Identity is framework-agnostic. The `@icp-sdk/auth` package works the same way in React, Vue, Svelte, and Next.js static export mode. See the [Internet Identity guide](../authentication/internet-identity.md) for integration steps. +Authentication with Internet Identity is framework-agnostic. The `@icp-sdk/auth` package works the same way in React, Vue, Svelte, and Next.js static export mode. See the [Internet Identity guide](../authentication/internet-identity.md#frontend-integration) for integration steps. ## Svelte and SvelteKit diff --git a/docs/guides/security/access-management.mdx b/docs/guides/security/access-management.mdx index 1c16b507..8c756eba 100644 --- a/docs/guides/security/access-management.mdx +++ b/docs/guides/security/access-management.mdx @@ -244,7 +244,7 @@ import Runtime "mo:core/Runtime"; -In Rust, there is no built-in `is_controller` function: checking controllers requires an async call to the management canister. See [inter-canister calls](../canister-calls/inter-canister-calls.md) for inter-canister call patterns. +In Rust, there is no built-in `is_controller` function: checking controllers requires an async call to the management canister. See [inter-canister calls](../canister-calls/inter-canister-calls.md#making-calls) for inter-canister call patterns. diff --git a/docs/guides/security/canister-upgrades.md b/docs/guides/security/canister-upgrades.md index 161a0b02..7e8ba7a2 100644 --- a/docs/guides/security/canister-upgrades.md +++ b/docs/guides/security/canister-upgrades.md @@ -124,7 +124,7 @@ fn pre_upgrade() { } ``` -When `pre_upgrade` traps due to instruction exhaustion, the canister cannot be upgraded. The `skip_pre_upgrade` flag (an emergency escape hatch via the management canister's `install_code` API (see [Management canister reference](../../references/management-canister.md)) bypasses the hook) but anything the hook would have saved is lost. Use stable structures so the upgrade path cannot brick itself under load. +When `pre_upgrade` traps due to instruction exhaustion, the canister cannot be upgraded. The `skip_pre_upgrade` flag (an emergency escape hatch via the management canister's `install_code` API (see [Management canister reference](../../references/management-canister.md#install_code)) bypasses the hook) but anything the hook would have saved is lost. Use stable structures so the upgrade path cannot brick itself under load. ## Candid interface compatibility @@ -342,7 +342,7 @@ See [Access management](access-management.md) for detailed controller management ## Next steps - [Data persistence](../backends/data-persistence.md): stable structures and upgrade patterns in depth -- [Canister lifecycle](../canister-management/lifecycle.md): the full upgrade sequence and install modes +- [Canister lifecycle](../canister-management/lifecycle.md#upgrade-a-canister): the full upgrade sequence and install modes - [Canister snapshots](../canister-management/snapshots.md): create and restore snapshots - [Testing strategies](../testing/strategies.md): test upgrade scenarios before deploying to mainnet - [Access management](access-management.md): manage controllers and prevent lock-out diff --git a/docs/guides/security/dos-prevention.md b/docs/guides/security/dos-prevention.md index d782f046..946284d7 100644 --- a/docs/guides/security/dos-prevention.md +++ b/docs/guides/security/dos-prevention.md @@ -28,7 +28,7 @@ Every ingress message (external call to your canister) costs cycles. The cost in - Per-instruction fees for all code executed before a trap or rejection - Candid decoding, which runs before your method body -This means an attacker can drain your cycles simply by sending many messages. The canister pays for Candid decoding and early checks even when it rejects the call. See [Cycles costs](../../references/cycles-costs.md) for exact figures. +This means an attacker can drain your cycles simply by sending many messages. The canister pays for Candid decoding and early checks even when it rejects the call. See [Cycles costs](../../references/cycles-costs.md#cost-table) for exact figures. ### Use inspect_message as a first-pass filter @@ -223,7 +223,7 @@ The IC enforces hard limits on message execution. If your canister frequently ap | Wasm heap memory | 4 GiB (wasm32) | | Wasm stable memory | 500 GiB | -Source: [Cycles costs reference](../../references/cycles-costs.md). +Source: [Cycles costs reference](../../references/cycles-costs.md#resource-limits). ### Prevent memory exhaustion @@ -288,7 +288,7 @@ canisters: compute_allocation: 10 # Guaranteed 10% of one execution core ``` -A value of `10` means the canister is scheduled at least every 10 consensus rounds. Compute allocation incurs an ongoing rental fee (10M cycles per percentage point per second on a 13-node subnet). Only set it if you need guaranteed throughput under load. See [Cycles costs](../../references/cycles-costs.md). +A value of `10` means the canister is scheduled at least every 10 consensus rounds. Compute allocation incurs an ongoing rental fee (10M cycles per percentage point per second on a 13-node subnet). Only set it if you need guaranteed throughput under load. See [Cycles costs](../../references/cycles-costs.md#compute-allocation). ### Memory allocation @@ -338,7 +338,7 @@ Chain-key signing (threshold ECDSA/Schnorr), HTTPS outcalls, and Bitcoin API cal - [Access management](access-management.md): caller checks, anonymous principal rejection, and role-based guards - [Inter-canister call safety](inter-canister-calls.md): TOCTOU vulnerabilities and the CallerGuard pattern - [Canister settings](../canister-management/settings.md): freezing threshold, memory allocation, and compute allocation -- [Cycles costs](../../references/cycles-costs.md): exact cost tables and resource limits +- [Cycles costs](../../references/cycles-costs.md#cost-table): exact cost tables and resource limits - [Security model](../../concepts/security.md): IC trust boundaries and threat model overview diff --git a/docs/guides/security/inter-canister-calls.md b/docs/guides/security/inter-canister-calls.md index 2b4572f9..2f5414b2 100644 --- a/docs/guides/security/inter-canister-calls.md +++ b/docs/guides/security/inter-canister-calls.md @@ -476,7 +476,7 @@ Before shipping any canister that makes inter-canister calls: ## Next steps -- [Inter-canister calls](../canister-calls/inter-canister-calls.md): Basic inter-canister call patterns and the `Call` API +- [Inter-canister calls](../canister-calls/inter-canister-calls.md#making-calls): Basic inter-canister call patterns and the `Call` API - [Parallel inter-canister calls](../canister-calls/parallel-inter-canister-calls.md): Running multiple calls concurrently and handling partial failures - [Security concepts](../../concepts/security.md): IC security model and threat landscape diff --git a/docs/guides/testing/pocket-ic.md b/docs/guides/testing/pocket-ic.md index f7e214c5..d331037f 100644 --- a/docs/guides/testing/pocket-ic.md +++ b/docs/guides/testing/pocket-ic.md @@ -377,7 +377,7 @@ PocketIC runs on macOS and Linux. Windows is not currently supported for standal ## Connecting to a running network for testing -For end-to-end tests that need a full network with all system canisters, use a containerized network instead of PocketIC. See the [icp-cli containerized networks documentation](https://cli.internetcomputer.org/) for how to configure Docker-based test networks in `icp.yaml`. +For end-to-end tests that need a full network with all system canisters, use a containerized network instead of PocketIC. See the [icp-cli containerized networks documentation](https://cli.internetcomputer.org/0.2/guides/containerized-networks) for how to configure Docker-based test networks in `icp.yaml`. The containerized network is appropriate when: diff --git a/docs/guides/testing/strategies.md b/docs/guides/testing/strategies.md index 901e6993..d417c1bf 100644 --- a/docs/guides/testing/strategies.md +++ b/docs/guides/testing/strategies.md @@ -330,7 +330,7 @@ icp network status docker-test --json For the full containerized network configuration reference: including environment variables, volume mounts, and custom images: see the -[icp-cli containerized networks guide](https://cli.internetcomputer.org/guides/containerized-networks). +[icp-cli containerized networks guide](https://cli.internetcomputer.org/0.2/guides/containerized-networks). ## Choosing the right approach diff --git a/docs/index.mdx b/docs/index.mdx index d3f1b163..8c662be2 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -39,7 +39,7 @@ Teach your AI coding agent the patterns, APIs, and deployment workflows it needs ## External resources - + diff --git a/docs/references/candid-spec.md b/docs/references/candid-spec.md index a37c8aa7..c61faf42 100644 --- a/docs/references/candid-spec.md +++ b/docs/references/candid-spec.md @@ -568,7 +568,7 @@ The supported annotations are: -   `oneway` indicates that this function returns no response, intended for fire-and-forget scenarios. -For more information about parameter naming, see [Naming arguments and results](../guides/canister-calls/candid.md#service-naming). +For more information about parameter naming, see [Naming arguments and results](../guides/canister-calls/candid.md#the-did-file). #### Type syntax ``` candid @@ -589,7 +589,7 @@ func "aaaaa-aa".create_canister ``` #### Subtypes -The following modifications to a function type change it to a subtype as discussed in the rules for [service upgrades](../guides/canister-calls/candid.md#upgrades): +The following modifications to a function type change it to a subtype as discussed in the rules for [service upgrades](../guides/canister-calls/candid.md#safe-interface-upgrades): -   The result type list may be extended. @@ -645,7 +645,7 @@ type F4 = shared query () -> async Text; Services may want to pass around references to not just individual functions (using the [`func` type](#type-func)), but references to whole services. In this case, Candid types can be used to declare the complete interface of such a service. -See [Candid service descriptions](../guides/canister-calls/candid.md#candid-service-descriptions) for more details on the syntax of a service type. +See [Candid service descriptions](../guides/canister-calls/candid.md#the-did-file) for more details on the syntax of a service type. #### Type syntax ``` candid @@ -667,7 +667,7 @@ service: "aaaaa-aa" #### Subtypes The subtypes of a service type are those service types that possibly have additional methods and where the type of an existing method is changed to a subtype. -This is exactly the same principle as discussed for upgrade rules in [service upgrades](../guides/canister-calls/candid.md#upgrades). +This is exactly the same principle as discussed for upgrade rules in [service upgrades](../guides/canister-calls/candid.md#safe-interface-upgrades). #### Supertypes The supertypes of a service type are those service types that may have some methods removed, and the type of existing methods is changed to a supertype. @@ -818,9 +818,9 @@ All types None, as this type has no values. diff --git a/docs/references/cycles-costs.md b/docs/references/cycles-costs.md index 24aa7d93..38a3374a 100644 --- a/docs/references/cycles-costs.md +++ b/docs/references/cycles-costs.md @@ -5,7 +5,7 @@ sidebar: order: 8 --- -Canisters pay for the resources they consume and operations they perform using [**cycles**](../concepts/cycles.md). The price of cycles is pegged to [XDR](glossary.md) (Special Drawing Rights): **1 trillion cycles = 1 XDR**. As of May 22, 2025, 1 XDR ≈ $1.35 USD: this rate fluctuates; see the [IMF's XDR exchange data](https://www.imf.org/external/np/fin/data/rms_sdrv.aspx) for the current rate. +Canisters pay for the resources they consume and operations they perform using [**cycles**](../concepts/cycles.md). The price of cycles is pegged to [XDR](glossary.md#xdr) (Special Drawing Rights): **1 trillion cycles = 1 XDR**. As of May 22, 2025, 1 XDR ≈ $1.35 USD: this rate fluctuates; see the [IMF's XDR exchange data](https://www.imf.org/external/np/fin/data/rms_sdrv.aspx) for the current rate. You can use the [pricing calculator](https://3d5wy-5aaaa-aaaag-qkhsq-cai.icp0.io/) to estimate the cost for your app. diff --git a/docs/references/developer-tools.md b/docs/references/developer-tools.md index 9cdc61b3..a2e1f816 100644 --- a/docs/references/developer-tools.md +++ b/docs/references/developer-tools.md @@ -18,9 +18,9 @@ Key features: - **Environments**: named deployment targets that combine a network, canister set, and settings (e.g., local, staging, production) - **Project scaffolding**: `icp new` bootstraps new projects from official templates -For installation, see the [Quickstart](../getting-started/quickstart.md) or the [full CLI documentation](https://cli.internetcomputer.org/). +For installation, see the [Quickstart](../getting-started/quickstart.md) or the [full CLI documentation](https://cli.internetcomputer.org/0.2/). -Advanced: [creating recipes](https://cli.internetcomputer.org/guides/creating-recipes) and [creating templates](https://cli.internetcomputer.org/guides/creating-templates) are documented on the CLI docs site. +Advanced: [creating recipes](https://cli.internetcomputer.org/0.2/guides/creating-recipes) and [creating templates](https://cli.internetcomputer.org/0.2/guides/creating-templates) are documented on the CLI docs site. icp-cli collects anonymous usage telemetry. Opt out with `icp settings telemetry false` or `DO_NOT_TRACK=1`. diff --git a/docs/references/digital-asset-standards.md b/docs/references/digital-asset-standards.md index 39673902..cab577e4 100644 --- a/docs/references/digital-asset-standards.md +++ b/docs/references/digital-asset-standards.md @@ -93,7 +93,7 @@ type TransferError = variant { | `icrc1:decimals` | `Nat` | `8` | | `icrc1:fee` | `Nat` | `10000` | -For a few well-known ledger canister IDs and index canisters, see [Ledgers](../guides/digital-assets/ledgers.md#well-known-token-ledgers). For a broader overview of tokens on ICP, see the [ICP Dashboard token list](https://dashboard.internetcomputer.org/tokens). +For a few well-known ledger canister IDs and index canisters, see [Ledgers](../guides/digital-assets/ledgers.md#well-known-ledgers). For a broader overview of tokens on ICP, see the [ICP Dashboard token list](https://dashboard.internetcomputer.org/tokens). [Read the full ICRC-1 standard](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1) diff --git a/docs/references/execution-errors.md b/docs/references/execution-errors.md index 5be01dc9..4505f972 100644 --- a/docs/references/execution-errors.md +++ b/docs/references/execution-errors.md @@ -27,7 +27,7 @@ Common root causes: - **Integer division by zero**: the canister attempted to divide by zero. Inspect the canister code for any division operations. - **Unreachable**: typically produced when a Rust canister panics. Rust canisters using `ic-cdk` macros automatically convert panics to `ic0.trap` calls with a human-readable message including the file, line, and panic reason. -To fix this error, test the canister to identify unhandled errors. Review the [canister trapping guide](../guides/canister-management/lifecycle.md) for detailed guidance on traps during upgrades and inter-canister calls. +To fix this error, test the canister to identify unhandled errors. Review the [canister trapping guide](../guides/canister-management/lifecycle.md#trapping-and-error-handling) for detailed guidance on traps during upgrades and inter-canister calls. ### Trapped explicitly @@ -38,7 +38,7 @@ The canister aborted execution by calling the `ic0.trap` system API. Canister called `ic0.trap` with message: ``` -When encountering an error, canisters may choose to fail with an error message by calling the [`ic0.trap` API](./ic-interface-spec/canister-interface.md). The Rust and Motoko CDKs insert calls to this API when panicking. +When encountering an error, canisters may choose to fail with an error message by calling the [`ic0.trap` API](./ic-interface-spec/canister-interface.md#system-api-imports). The Rust and Motoko CDKs insert calls to this API when panicking. To fix this error, test the canister to determine which inputs trigger panics. Review the error message embedded in the trap to identify the source of the failure. @@ -159,7 +159,7 @@ Canister cannot grow memory by 65536 bytes due to insufficient cycles. Canisters pay for their memory each round. Growing memory requires that the canister have enough cycles to pay for the increased usage. For operations like uploading a Wasm chunk, taking a snapshot, or installing code, the error message may include an "At least X additional cycles are required" suffix indicating the shortfall. -To fix this error, top up the canister with more cycles. See the [cycles management guide](../guides/canister-management/cycles-management.md). +To fix this error, top up the canister with more cycles. See the [cycles management guide](../guides/canister-management/cycles-management.md#topping-up-canisters). ### Reserved cycles limit exceeded in memory grow @@ -211,7 +211,7 @@ Canister cannot grow message memory by 10240 bytes due to insufficient cycles. Sending a message to another canister reserves space in subnet memory for the message and its response. This error means the canister doesn't have enough cycles to pay for that memory without freezing. -To fix this error, top up the canister with more cycles. See the [cycles management guide](../guides/canister-management/cycles-management.md). +To fix this error, top up the canister with more cycles. See the [cycles management guide](../guides/canister-management/cycles-management.md#topping-up-canisters). ### Insufficient cycles in compute allocation @@ -224,7 +224,7 @@ Cannot increase compute allocation to 50 due to insufficient cycles. At least 10 Canisters pay for compute allocation. This error means an attempt was made to increase the compute allocation beyond what the canister can currently pay for. -To fix this error, top up the canister with more cycles. See the [cycles management guide](../guides/canister-management/cycles-management.md). +To fix this error, top up the canister with more cycles. See the [cycles management guide](../guides/canister-management/cycles-management.md#topping-up-canisters). ### Insufficient cycles in memory allocation @@ -237,7 +237,7 @@ Cannot increase memory allocation to 40000000000 due to insufficient cycles. At Canisters pay for memory allocation. This error means an attempt was made to increase the memory allocation beyond what the canister can currently pay for. -To fix this error, top up the canister with more cycles. See the [cycles management guide](../guides/canister-management/cycles-management.md). +To fix this error, top up the canister with more cycles. See the [cycles management guide](../guides/canister-management/cycles-management.md#topping-up-canisters). ### Install code not enough cycles @@ -248,7 +248,7 @@ A canister doesn't have enough cycles to execute an install message. Canister installation failed with `Canister xxx-xxx is out of cycles: please top up the canister with at least 10000000000 additional cycles`. ``` -To fix this error, top up the canister with additional cycles before retrying the installation. See the [cycles management guide](../guides/canister-management/cycles-management.md). +To fix this error, top up the canister with additional cycles before retrying the installation. See the [cycles management guide](../guides/canister-management/cycles-management.md#topping-up-canisters). ### Create canister not enough cycles @@ -558,7 +558,7 @@ There was an attempt to install code on a canister that already has code install Canister xxx-xxx cannot be installed because the canister is not empty. Try installing with mode='reinstall' instead. ``` -Installing a Wasm module is only for canisters that have no existing state. If the intention is to update the Wasm module while preserving state, use an [upgrade](../guides/canister-management/lifecycle.md) instead. If the intention is to overwrite the canister state entirely, use `reinstall` mode. +Installing a Wasm module is only for canisters that have no existing state. If the intention is to update the Wasm module while preserving state, use an [upgrade](../guides/canister-management/lifecycle.md#upgrade-a-canister) instead. If the intention is to overwrite the canister state entirely, use `reinstall` mode. ### Delete canister not stopped diff --git a/docs/references/ic-interface-spec/canister-interface.md b/docs/references/ic-interface-spec/canister-interface.md index c7f5d8a8..52c49ce0 100644 --- a/docs/references/ic-interface-spec/canister-interface.md +++ b/docs/references/ic-interface-spec/canister-interface.md @@ -929,7 +929,7 @@ These system calls return costs in Cycles, represented by 128 bits, which will b - `algorithm: 0 → bip340secp256k1, 1 → ed25519` - `vetkd_curve: 0 → bls12_381` - See [`sign_with_ecdsa`](./management-canister.md#ic-sign_with_ecdsa), [`sign_with_schnorr`](./management-canister.md#ic-sign_with_schnorr) and [`vetkd_encrypted_key`](#ic-vetkd_encrypted_key) for more information. + See [`sign_with_ecdsa`](./management-canister.md#ic-sign_with_ecdsa), [`sign_with_schnorr`](./management-canister.md#ic-sign_with_schnorr) and [`vetkd_derive_key`](./management-canister.md#ic-vetkd_derive_key) for more information. These system calls trap if `src` + `size` or `dst` + 16 exceed the size of the WebAssembly memory. Otherwise, they return an `i32` with the following meaning: - `0`: Success. The result can be found at the memory address `dst`. diff --git a/docs/references/ic-interface-spec/management-canister.md b/docs/references/ic-interface-spec/management-canister.md index 315ec511..a221dee2 100644 --- a/docs/references/ic-interface-spec/management-canister.md +++ b/docs/references/ic-interface-spec/management-canister.md @@ -789,9 +789,9 @@ This method returns all metadata of a snapshot identified by `snapshot_id` of th The returned metadata of a snapshot contain: -- the "source" of the snapshot, i.e., whether the snapshot was created by taking the canister state using the method [`take_canister_snapshot`](#ic-take_canister_snapshot) or by (snapshot) metadata upload using the method [`upload_canister_snapshot_metadata`](#ic_upload_canister_snapshot_metadata); +- the "source" of the snapshot, i.e., whether the snapshot was created by taking the canister state using the method [`take_canister_snapshot`](#ic-take_canister_snapshot) or by (snapshot) metadata upload using the method [`upload_canister_snapshot_metadata`](#ic-upload_canister_snapshot_metadata); -- the timestamp at which the snapshot was created, i.e., the method [`take_canister_snapshot`](#ic-take_canister_snapshot) or [`upload_canister_snapshot_metadata`](#ic_upload_canister_snapshot_metadata) executed; +- the timestamp at which the snapshot was created, i.e., the method [`take_canister_snapshot`](#ic-take_canister_snapshot) or [`upload_canister_snapshot_metadata`](#ic-upload_canister_snapshot_metadata) executed; - the size of the canister WASM (in bytes); @@ -801,7 +801,7 @@ The returned metadata of a snapshot contain: - hashes of chunks in the WASM chunk store; -- the [canister version](./canister-interface.md#system-api-canister-version) when the snapshot was created, i.e., the method [`take_canister_snapshot`](#ic-take_canister_snapshot) or [`upload_canister_snapshot_metadata`](#ic_upload_canister_snapshot_metadata) executed; +- the [canister version](./canister-interface.md#system-api-canister-version) when the snapshot was created, i.e., the method [`take_canister_snapshot`](#ic-take_canister_snapshot) or [`upload_canister_snapshot_metadata`](#ic-upload_canister_snapshot_metadata) executed; - the [certified data](./canister-interface.md#system-api-certified-data); From e36a7527858618edcba53901bc2cf049433fb42b Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Tue, 5 May 2026 10:45:35 +0200 Subject: [PATCH 2/3] docs(agents): add icp-cli version slug update checklist to submodule bump instructions --- AGENTS.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2468fda0..a255acde 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -144,7 +144,7 @@ git checkout main - 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 ` 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 "^## \|^### " `. 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/` and verify the path exists in `.sources/icp-cli/docs/.md`. For command-specific links, add a section anchor derived from the heading in `.sources/icp-cli/docs/reference/cli.md` (e.g. `#icp-canister-logs`, `#icp-canister-settings-update`, `#icp-cycles`). When the icp-cli version is bumped, update the version prefix in all CLI doc links. +- Link to `https://cli.internetcomputer.org/` (bare root) — all CLI doc pages are under a versioned path. Use `https://cli.internetcomputer.org/0.2/` (current slug; verify with `cat .sources/icp-cli/docs-site/versions.json`) and confirm the path exists in `.sources/icp-cli/docs/.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.) @@ -283,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 | @@ -297,6 +297,19 @@ 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. Find all CLI doc links in the docs: `grep -rn "cli.internetcomputer.org" docs/ --include="*.md" --include="*.mdx"` +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. Verify the target paths still exist under the new version: `ls .sources/icp-cli/docs/.md` for any path that changed in the bump. +5. 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 From 10643a05c1393c3419ba2909665fc5145482e0c4 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Tue, 5 May 2026 10:48:50 +0200 Subject: [PATCH 3/3] docs(agents): verify icp-cli link paths exist before bumping version slug --- AGENTS.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a255acde..2f9c48c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -300,15 +300,22 @@ EOF **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. Find all CLI doc links in the docs: `grep -rn "cli.internetcomputer.org" docs/ --include="*.md" --include="*.mdx"` +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. Verify the target paths still exist under the new version: `ls .sources/icp-cli/docs/.md` for any path that changed in the bump. -5. Run `npm run build` to confirm no broken links. +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