docs(info): review root README to integrate @icp-sdk/canisters

README.md

@@ -1,28 +1,57 @@
-# 📦 ic-js
+# 📦 `@icp-sdk/canisters`
 
-A collection of library for interfacing with the Internet Computer.
+A modular library for interacting with canisters on the Internet Computer.
 
 [![Internet Computer portal](https://img.shields.io/badge/Internet-Computer-grey?logo=internet%20computer)](https://internetcomputer.org)
 [![Checks Status](https://img.shields.io/github/actions/workflow/status/dfinity/ic-js/checks.yml?logo=github&label=Build%20and%20checks)](https://github.com/dfinity/ic-js/actions/workflows/checks.yml)
 [![GitHub Latest Release)](https://img.shields.io/github/v/release/dfinity/ic-js?logo=github&label=Last%20release)](https://github.com/dfinity/ic-js/releases)
 
-## Libraries
+## Introduction
 
-- [nns](/packages/nns): interfacing with the **governance** canisters of the Network Nervous System (NNS)
-- [sns](/packages/sns): interacting with a Service Nervous System (SNS) project
-- [cmc](/packages/cmc): interfacing with the **cmc** canister of the IC
-- [ledger-icp](/packages/ledger-icp): interfacing with the **ICP** ledger
-- [ledger-icrc](/packages/ledger-icrc): interacting with **ICRC** compatible ledgers
-- [ckBTC](/packages/ckbtc): interfacing with **ckBTC**
-- [ckETH](/packages/cketh): interfacing with **ckETH**
-- [ic-management](/packages/ic-management): interfacing with the **IC management canister**
-- [utils](/packages/utils): a collection of utilities and constants
-- [zod-schemas](/packages/zod-schemas): a collection of reusable Zod schemas and validators for common data patterns in ICP applications
-- [nns-proto](/packages/nns-proto): the protobuf source used by `nns-js` to support hardware wallets
+This repository provides an SDK designed to make it easy to interact with Internet Computer canisters when developing frontend applications or Node.js scripts in TypeScript or JavaScript.
+
+### ✅ Recommended
+
+- [`@icp-sdk/canisters`](/packages/canisters): a **modular entry-point library** exposing various submodules for interacting with well-known Internet Computer canisters and services.
+
+### 🧩 Legacy single-entry packages
+
+The following libraries are exposed by the modular subpath-only library above, but remain available and are released in parallel for backward compatibility:
+
+- [`@dfinity/nns`](/packages/nns): interfacing with the **governance** canisters of the Network Nervous System (NNS)
+- [`@dfinity/sns`](/packages/sns): interacting with a Service Nervous System (SNS) project
+- [`@dfinity/cmc`](/packages/cmc): interfacing with the **CMC** canister of the IC
+- [`@dfinity/ledger-icp`](/packages/ledger-icp): interfacing with the **ICP** ledger
+- [`@dfinity/ledger-icrc`](/packages/ledger-icrc): interacting with **ICRC**-compatible ledgers
+- [`@dfinity/ckbtc`](/packages/ckbtc): interfacing with **ckBTC**
+- [`@dfinity/cketh`](/packages/cketh): interfacing with **ckETH**
+- [`@dfinity/ic-management`](/packages/ic-management): interfacing with the **IC management canister**
+
+### 🧰 Utilities
+
+This repo also provides various tools that are used internally by the SDK packages but also prove to be extremely useful when developing projects.
+
+- [`@dfinity/utils`](/packages/utils): a collection of utilities and constants
+- [`@dfinity/zod-schemas`](/packages/zod-schemas): reusable Zod schemas and validators for common data patterns in ICP applications
+
+> [!NOTE]  
+> `@dfinity/utils` is a peer dependency of the libraries exposed by `@icp-sdk/canisters` but is not itself re-exported by this library.
+
+### 🗃️ Deprecated
+
+While not deprecated on npm, the following library is no longer actively developed:
+
+- [`@dfinity/nns-proto`](/packages/nns-proto): protobuf sources formerly used by `nns-js` to support hardware wallets.
 
 ## Installation
 
-Install any library of this repo in your project from [npm](https://www.npmjs.com):
+Install the recommended modular library from [npm](https://www.npmjs.com):
+
+```bash
+npm i @icp-sdk/canisters
+```
+
+Or, if you prefer to install individual packages:
 
 ```bash
 npm i @dfinity/utils
@@ -34,10 +63,9 @@ npm i @dfinity/cmc
 npm i @dfinity/ckbtc
 ```
 
-You may be using all libraries in your project - as we do in [NNS-dapp](https://github.com/dfinity/nns-dapp/).
-That is s why, to help tree-shaking and avoid duplication of code, the libraries of this project are referencing [agent-js](https://github.com/dfinity/agent-js) and [utils](/packages/utils) as peer dependencies.
+To ensure proper tree-shaking and avoid code duplication, all packages reference [`@icp-sdk/core](https://github.com/dfinity/icp-js-core) and [`@dfinity/utils`](/packages/utils) as peer dependencies.
 
-Therefore, be sure that the needed `agent-js` and [utils](/packages/utils) dependencies are available in your project or install these as following:
+Make sure these are installed in your project:
 
 ```bash
 npm i @icp-sdk/core @dfinity/utils
@@ -48,3 +76,5 @@ npm i @icp-sdk/core @dfinity/utils
 Here are some useful links:
 
 - See the [HACKING](/HACKING.md) document for some information about local development
+- [CHANGELOG](/CHANGELOG.md) or [Releases](https://github.com/dfinity/ic-js/releases) for version history
+- [ADMIN](/ADMIN.md) for notes on repository administration