docs: improve config dependencies page

Author: zkochan

docs/config-dependencies.md

@@ -1,49 +1,60 @@
 ---
 id: config-dependencies
-title: Config dependencies
+title: Config Dependencies
 ---
 
-Config dependencies are installed before all the other types of dependencies (before "dependencies", "devDependencies", "optionalDependencies").
+Config dependencies allow you to share and centralize configuration files, settings, and hooks across multiple projects. They are installed before all regular dependencies ("dependencies", "devDependencies", "optionalDependencies"), making them ideal for setting up custom hooks, patches, and catalog entries.
 
-Config dependencies cannot have dependencies of their own or lifecycle scripts. They should be added using exact version and the integrity checksum. Example:
+Config dependencies help you keep all the hooks, settings, patches, overrides, catalogs, rules in a single place and use them across multiple repositories.
+
+## How to Add a Config Dependency
+
+Config dependencies are defined in your `pnpm-workspace.yaml` and must be installed using an exact version and an integrity checksum.
+
+Example:
 
 ```yaml title="pnpm-workspace.yaml"
 configDependencies:
   my-configs: "1.0.0+sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw=="
 ```
 
+**Important:**
+
+* Config dependencies **cannot** have their own dependencies.
+* Config dependencies **cannot** define lifecycle scripts (like `preinstall`, `postinstall`, etc.).
+
 ## Usage
 
-### Loading an allow list of built dependencies
+### Loading an Allow List of Built Dependencies
 
-You may load a list of package names that are allowed to be built via config dependencies and the [`onlyBuiltDependenciesFile`] setting. For example, you may publish a package with an `allow.json` file in its root directory:
+You can load a list of package names that are allowed to be built, using the [`onlyBuiltDependenciesFile`] setting.
 
-```json
+Example `allow.json` file inside a config dependency:
+
+```json title="allow.json"
 [
   "esbuild",
   "fsevents"
 ]
 ```
 
-Let's say this package is called `my-configs`, then your project's `pnpm-workspace.yaml` will look like this:
+Your workspace configuration:
 
-```yaml
+```yaml title="pnpm-workspace.yaml"
 configDependencies:
   my-configs: "1.0.0+sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw=="
 onlyBuiltDependenciesFile: "node_modules/.pnpm-config/my-configs/allow.json"
 ```
 
-This way your project will load the list of packages that are allowed to be built from `my-configs`.
-
 [`onlyBuiltDependenciesFile`]: settings.md#onlybuiltdependenciesfile
 
-### Installing dependencies used in hooks
+### Installing Dependencies Used in Hooks
 
-Config dependencies are installed before the hooks from [`.pnpmfile.cjs`] are loaded, so you can use them as dependencies for your hooks.
+Config dependencies are installed **before** hooks from your [`.pnpmfile.cjs`] are loaded, allowing you to import logic from config packages.
 
-For instance, you may have a config dependency called "my-hooks" that exports a `readPackage` hook. In this case, you can import it into your `.pnpmfile.cjs` like this:
+Example:
 
-```js
+```js title=".pnpmfile.cjs"
 const { readPackage } = require('.pnpm-config/my-hooks')
 
 module.exports = {
@@ -55,11 +66,11 @@ module.exports = {
 
 [`.pnpmfile.cjs`]: ./pnpmfile.md
 
-#### Loading any type of settings
+### Updating pnpm Settings Dynamically
 
-Using the [`updateConfig`] hook, you can dynamically update any configuration settings used by pnpm. Because hooks can be loaded from config dependencies, you can also share settings across projects by publishing them as config dependencies.
+Using the [`updateConfig`] hook, you can dynamically update pnpm’s settings using config dependencies.
 
-For example, the following pnpmfile defines a hook that adds a new [catalog] entry to pnpm's configuration. This allows you to refer to the catalog entry when specifying dependency versions:
+For example, the following `pnpmfile` adds a new [catalog] entry to pnpm's configuration:
 
 ```js title="my-catalogs/pnpmfile.cjs"
 module.exports = {
@@ -73,21 +84,21 @@ module.exports = {
 }
 ```
 
-You can publish this pnpmfile inside a config dependency. Once published and installed, you can load it by specifying the following settings in your `pnpm-workspace.yaml`:
+Install and load it:
 
-```yaml
+```yaml title="pnpm-workspace.yaml"
 configDependencies:
   my-catalogs: "1.0.0+sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw=="
 pnpmfile: "node_modules/.pnpm-config/my-catalogs/pnpmfile.cjs"
 ```
 
-Now, you can run:
+Then you can run:
 
 ```
 pnpm add is-odd@catalog:
 ```
 
-This will install `[email protected]` into your `node_modules`, and add the following entry to your `package.json`:
+This will install `[email protected]` and add the following to your `package.json`:
 
 ```json
 {
@@ -99,14 +110,16 @@ This will install `[email protected]` into your `node_modules`, and add the following
 
 This makes it easy to maintain and share centralized configuration and dependency versions across projects.
 
-[updateConfig]: ./pnpmfile.md#hooksupdateconfigconfig-config--promiseconfig
+[`updateConfig`]: ./pnpmfile.md#hooksupdateconfigconfig-config--promiseconfig
 [catalog]: ./catalogs.md
 
-### Loading patches
+### Loading Patch Files
+
+You can reference [patch files] stored inside config dependencies.
 
-You can reference [patch files] installed via config dependencies. For instance, if you have a config dependency called "my-patches", you can load patches from it:
+Example:
 
-```yaml
+```yaml title="pnpm-workspace.yaml"
 configDependencies:
   my-patches: "1.0.0+sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw=="
 patchedDependencies: