docs: v5 upgrading guide touches (#1265)

# Description

Minor updates to the v5 upgrading guide, mainly adding more links to the
API.

Author: ilbertt

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+See the [v5 upgrading guide](https://js.icp.build/core/v5/upgrading/v5/) for more information.
+
 - feat(core)!: removes `@dfinity/{agent,candid,identity,identity-secp256k1,principal}` peer dependencies and moves their source code to the `@icp-sdk/core` package
 - feat(agent)!: use `/api/v4` for call requests
   - Renames `v3ResponseBody` to `v4ResponseBody`

docs/src/content/docs/upgrading/v5.md

@@ -14,12 +14,12 @@ This release completes the migration of all `@dfinity/*` packages into `@icp-sdk
 ## TL;DR
 
 - **New API versions**: Agent now uses the latest IC API endpoints: `/api/v4` for calls and `/api/v3` for queries/read_state.
-- **Local replica upgrade required**: Use dfx >=v0.30.1 or PocketIC >=v11.0.0.
+- **Local replica upgrade required**: Use dfx >=[v0.30.1](https://github.com/dfinity/sdk/releases/tag/0.30.1) or PocketIC >=[v11.0.0](https://github.com/dfinity/pocketic/releases/tag/11.0.0).
 - **Peer dependencies removed**: `@dfinity/*` packages are no longer peer dependencies. Remove them before upgrading.
 
 ## Before You Begin
 
-Before upgrading to v5, you **must** remove the `@dfinity/*` peer dependencies from your project. These packages are now fully integrated into `@icp-sdk/core` and are no longer required as separate dependencies.
+Before upgrading to v5, you **must** remove the `@dfinity/{agent,candid,identity,identity-secp256k1,principal}` (peer) dependencies from your project. These packages are now fully integrated into `@icp-sdk/core` and are no longer required as separate dependencies.
 
 ```shell
 npm remove @dfinity/{agent,candid,identity,identity-secp256k1,principal}
@@ -31,14 +31,32 @@ Then, upgrade `@icp-sdk/core` to the latest version:
 npm install @icp-sdk/core@latest
 ```
 
+> **NOTE**: If your project is using any package from the old `ic-js` suite (see [Legacy single-entry packages](https://github.com/dfinity/icp-js-canisters/blob/5fc7e162f0622dd335bb163f2dc3ab2c5325d16c/README.md#-legacy-single-entry-packages)), you should migrate to the new [`@icp-sdk/canisters`](https://js.icp.build/canisters/) package, which also doesn't depend on the `@dfinity/{agent,candid,identity,identity-secp256k1,principal}` packages.
+
 ## Breaking Changes
 
 ### Source Code Moved to `@icp-sdk/core`
 
 In v4, `@icp-sdk/core` re-exported the `@dfinity/*` packages as peer dependencies. In v5, the source code of all core packages has been moved directly into `@icp-sdk/core`. This means:
 
 - You no longer need to install `@dfinity/agent`, `@dfinity/candid`, `@dfinity/identity`, `@dfinity/identity-secp256k1`, or `@dfinity/principal` as separate packages.
-- All imports should use `@icp-sdk/core/*` submodules, as described in the [v4 upgrading guide](https://js.icp.build/core/latest/upgrading/v4/).
+- All imports should use `@icp-sdk/core/*` submodules:
+   | Old Import                    | New Import                         |
+   | ----------------------------- | ---------------------------------- |
+   | `@dfinity/agent`              | `@icp-sdk/core/agent`              |
+   | `@dfinity/candid`             | `@icp-sdk/core/candid`             |
+   | `@dfinity/identity`           | `@icp-sdk/core/identity`           |
+   | `@dfinity/identity-secp256k1` | `@icp-sdk/core/identity/secp256k1` |
+   | `@dfinity/principal`          | `@icp-sdk/core/principal`          |
+
+   E.g.
+
+   ```ts
+   - import { HttpAgent } from '@dfinity/agent';
+   + import { HttpAgent } from '@icp-sdk/core/agent';
+   ```
+
+   See more details in the [v4 upgrading guide](../upgrading/v4.md).
 
 ### API Version Upgrades
 
@@ -49,15 +67,17 @@ The agent now uses the latest IC API endpoints:
 
 If you were using internal types related to these API versions, you'll need to update them:
 
-| Old Name                        | New Name                        |
-| ------------------------------- | ------------------------------- |
-| `v3ResponseBody`                | `v4ResponseBody`                |
-| `isV3ResponseBody`              | `isV4ResponseBody`              |
-| `HttpV3ApiNotSupportedErrorCode`| `HttpV4ApiNotSupportedErrorCode`|
+| Old Name                        | New Name                                                                                        |
+| ------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `v3ResponseBody`                | [`v4ResponseBody`](../libs/agent/api/interfaces/v4ResponseBody.md)                              |
+| `isV3ResponseBody`              | [`isV4ResponseBody`](../libs/agent/api/functions/isV4ResponseBody.md)                           |
+| `HttpV3ApiNotSupportedErrorCode`| [`HttpV4ApiNotSupportedErrorCode`](../libs/agent/api/classes/HttpV4ApiNotSupportedErrorCode.md) |
+
+> If you're developing locally with **dfx**, make sure you upgrade to [v0.30.1](https://github.com/dfinity/sdk/releases/tag/0.30.1) or later.
 
-> If you're developing locally, make sure you upgrade to [dfx v0.30.1](https://github.com/dfinity/sdk/releases/tag/0.30.1) or later.
+> If you're using **PocketIC** for testing, upgrade to [v11.0.0](https://github.com/dfinity/pocketic/releases/tag/11.0.0) or later.
 
-> If you're using PocketIC for testing, upgrade to [v11](https://github.com/dfinity/pocketic/releases/tag/11.0.0) or later.
+> If you're using [`@dfinity/pic-js`](https://js.icp.build/pic-js/) for testing, upgrade to [v0.17.0](https://github.com/dfinity/pic-js/releases/tag/0.17.0) or later.
 
 ### Certificate Verification: `canisterId` Replaced with `principal`
 
@@ -101,6 +121,8 @@ const certificate = await Certificate.create({
 });
 ```
 
+See more details in the [`CreateCertificateOptions`](../libs/agent/api/interfaces/CreateCertificateOptions.md) API docs.
+
 ## New Features
 
 ### Subnet State Methods
@@ -122,6 +144,12 @@ const subnetState = await agent.readSubnetState(subnetId, paths);
 await agent.syncTimeWithSubnet(subnetId);
 ```
 
+API docs:
+
+- [`HttpAgent.getSubnetIdFromCanister`](../libs/agent/api/classes/HttpAgent.md#getsubnetidfromcanister)
+- [`HttpAgent.readSubnetState`](../libs/agent/api/classes/HttpAgent.md#readsubnetstate)
+- [`HttpAgent.syncTimeWithSubnet`](../libs/agent/api/classes/HttpAgent.md#synctimewithsubnet)
+
 ### Canister Ranges Lookup
 
 New utility functions for looking up canister ranges from certificate trees:
@@ -148,9 +176,13 @@ const ranges = decodeCanisterRanges(canisterRanges);
 console.log(ranges);
 ```
 
+API docs:
+- [`lookupCanisterRanges`](../libs/agent/api/functions/lookupCanisterRanges.md)
+- [`decodeCanisterRanges`](../libs/agent/api/functions/decodeCanisterRanges.md)
+
 ### Subnet Status Utility
 
-A new `SubnetStatus` namespace has been introduced to request subnet information directly from the IC public API:
+A new [`SubnetStatus`](../libs/agent/api/namespaces/SubnetStatus/index.md) namespace has been introduced to request subnet information directly from the IC public API:
 
 ```typescript
 import { SubnetStatus } from '@icp-sdk/core/agent';
@@ -172,8 +204,8 @@ console.log(nodeKeys);
 
 ### Certificate Utilities
 
-- `getSubnetIdFromCertificate`: Read the subnet ID from a certificate tree
-- `IC_STATE_ROOT_DOMAIN_SEPARATOR`: Exported constant for certificate verification
+- `getSubnetIdFromCertificate`: Read the subnet ID from a certificate tree ([API docs](../libs/agent/api/functions/getSubnetIdFromCertificate.md))
+- `IC_STATE_ROOT_DOMAIN_SEPARATOR`: Exported constant for certificate verification ([API docs](../libs/agent/api/variables/IC_STATE_ROOT_DOMAIN_SEPARATOR.md))
 
 ## `@dfinity/auth-client` has been deprecated