docs: improvements + additions to module docs

www/apps/book/app/advanced-development/module-links/custom-columns/page.mdx

@@ -0,0 +1,174 @@
+export const metadata = {
+  title: `${pageNumber} Add Columns to a Link`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn how to add custom columns to a link definition and manage them.
+
+## How to Add Custom Columns to a Link's Table?
+
+The `defineLink` function used to define a link accepts a third paramter, which is an object of options.
+
+To add custom columns to a link's table, pass in the third parameter of `defineLink` a `database` property:
+
+export const linkHighlights = [
+  ["10", "extraColumns", "Custom columns to add to the created link's table."],
+  ["11", "metadata", "The column's name."],
+  ["12", "type", "The column's type."]
+]
+
+```ts highlights={linkHighlights}
+import HelloModule from "../modules/hello"
+import ProductModule from "@medusajs/medusa/product"
+import { defineLink } from "@medusajs/framework/utils"
+
+export default defineLink(
+  ProductModule.linkable.product,
+  HelloModule.linkable.myCustom,
+  {
+    database: {
+      extraColumns: {
+        metadata: {
+          type: "json",
+        }
+      }
+    }
+  }
+)
+```
+
+This adds to the table created for the link between `product` and `myCustom` a `metadata` column of type `json`.
+
+### Database Options
+
+The `database` property defines configuration for the table created in the database.
+
+Its `extraColumns` property defines custom columns to create in the link's table.
+
+`extraColumns`'s value is an object whose keys are the names of the columns, and values are the column's configurations as an object.
+
+### Column Configurations
+
+The column's configurations object accepts the following properties:
+
+- `type`: The column's type. Possible values are:
+    - `string`
+    - `text`
+    - `integer`
+    - `boolean`
+    - `date`
+    - `time`
+    - `datetime`
+    - `enum`
+    - `json`
+    - `array`
+    - `enumArray`
+    - `float`
+    - `double`
+    - `decimal`
+    - `bigint`
+    - `mediumint`
+    - `smallint`
+    - `tinyint`
+    - `blob`
+    - `uuid`
+    - `uint8array`
+- `defaultValue`: The column's default value.
+- `nullable`: Whether the column can have `null` values.
+
+---
+
+## Set Custom Column when Creating Link
+
+The object you pass to the remote link's `create` method accepts a `data` property. Its value is an object whose keys are custom column names, and values are the value of the custom column for this link.
+
+For example:
+
+<Note>
+
+Learn more about the remote link, how to resolve it, and its methods in [this chapter](../remote-link/page.mdx).
+
+</Note>
+
+```ts
+await remoteLink.create({
+  [Modules.PRODUCT]: {
+    product_id: "123"
+  },
+  HELLO_MODULE: {
+    my_custom_id: "321"
+  },
+  data: {
+    metadata: {
+      test: true
+    }
+  }
+})
+```
+
+---
+
+## Retrieve Custom Column with Link
+
+To retrieve linked records with their custom columns, use Query and pass the link definition as the `entity` property's value.
+
+For example:
+
+<Note>
+
+Learn more about Query and how to resolve use it [this chapter](../remote-link/page.mdx).
+
+</Note>
+
+export const retrieveHighlights = [
+  ["1", "productHelloLink", "Import the exported link definition."],
+  ["6", "entity", "Pass the link definition to retrieve its data."],
+  ["7", `"metadata"`, "Retrieve the `metadata` column."],
+  ["7", `"product.*"`, "Retrieve the linked product's details."],
+  ["7", `"my_custom.*"`, "Retrieve the linked `myCustom` record's details."],
+]
+
+```ts highlights={retrieveHighlights}
+import productHelloLink from "../links/product-hello"
+
+// ...
+
+const { data } = await query.graph({
+  entity: productHelloLink.entryPoint,
+  fields: ["metadata", "product.*", "my_custom.*"],
+  filters: {
+    product_id: "prod_123"
+  }
+})
+```
+
+This retrieves the product of id `prod_123` and its linked `my_custom` records.
+
+In the `fields` array you pass `metadata`, which is the custom column to retrieve of the link.
+
+---
+
+## Update Custom Column's Value
+
+The remote link's `create` method updates a link's data if the link between the specified records already exists.
+
+So, to update the value of a custom column in a created link, use the `create` method again passing it a new value for the custom column.
+
+For example:
+
+```ts
+await remoteLink.create({
+  [Modules.PRODUCT]: {
+    product_id: "123"
+  },
+  HELLO_MODULE: {
+    my_custom_id: "321"
+  },
+  data: {
+    metadata: {
+      test: false
+    }
+  }
+})
+```

www/apps/book/app/advanced-development/modules/module-link-directions/page.mdx → www/apps/book/app/advanced-development/module-links/directions/page.mdx

@@ -4,7 +4,7 @@ export const metadata = {
 
 # {metadata.title}
 
-In this chapter, you'll learn about difference in module link directions, and which to use based on your use case.
+In this chapter, you'll learn about the difference in module link directions, and which to use based on your use case.
 
 ## Link Direction
 

www/apps/book/app/advanced-development/modules/module-links/page.mdx → www/apps/book/app/advanced-development/module-links/page.mdx

@@ -1,30 +1,16 @@
-import { BetaBadge } from "docs-ui"
-
 export const metadata = {
   title: `${pageNumber} Module Link`,
 }
 
-# {metadata.title} <BetaBadge text="Beta" tooltipText="Module links are in active development." />
+# {metadata.title}
 
 In this chapter, you’ll learn what a module link is.
 
 ## What is a Module Link?
 
-A module link forms an association between two data models of different modules, while maintaining module isolation.
-
-You can then retrieve data across the linked modules, and manage their linked records.
-
-<Note title="Use module links when" type="success">
-
-You want to create a relation between data models from different modules.
+Since modules are isolated, you can't access another module's data models to add a relation to it or extend it.
 
-</Note>
-
-<Note title="Don't use module links if" type="error">
-
-You want to create a relationship between data models in the same module. Use data model relationships instead.
-
-</Note>
+Instead, you use a module link. A module link forms an association between two data models of different modules, while maintaining module isolation.
 
 ---
 
@@ -58,12 +44,14 @@ In this example, you define a module link between the `hello` module's `MyCustom
 
 ### 2. Sync Links
 
-Medusa stores links as pivot tables in the database. So, to reflect your link in the database, run the `db:sync-links` command:
+After defining the link, run the `db:sync-links` command:
 
 ```bash
 npx medusa db:sync-links
 ```
 
+The Medusa application creates a new table for your link to store the IDs of linked records.
+
 Use this command whenever you make changes to your links. For example, run this command if you remove your link definition file.
 
 <Note title="Tip">
@@ -74,6 +62,33 @@ You can also use the `db:migrate` command, which both runs the migrations and sy
 
 ---
 
+## How Module Links Work?
+
+When you define a module link, the Medusa application creates a table in the database for that link.
+
+Then, when you create links between records of the data models, the IDs of these data models are stored as a new record in the link's table.
+
+![Diagram illustration for links](https://res.cloudinary.com/dza7lstvk/image/upload/v1726482168/Medusa%20Book/Custom_Link_Illustration_fsisfa.jpg)
+
+---
+
+## When to Use Module Links
+
+<Note title="Use module links when" type="success">
+
+- You want to create a relation between data models from different modules.
+- You want to extend the data model of another module.
+
+</Note>
+
+<Note title="Don't use module links if" type="error">
+
+You want to create a relationship between data models in the same module. Use data model relationships instead.
+
+</Note>
+
+---
+
 ## Define a List Link
 
 By default, the defined link establishes a one-to-one relation: a record of a data model is linked to one record of the other data model.
@@ -105,23 +120,6 @@ In this example, a record of `product` can be linked to more than one record of
 
 ---
 
-## Extend Data Models with Module Links
-
-Module links are most useful when you want to add properties to a data model of another module.
-
-For example, to add custom properties to the `Product` data model of the Product Module, you:
-
-1. Create a module.
-2. Create in the module a data model that holds the custom properties you want to add to the `Product` data model.
-2. Define a module link that links your module to the Product Module.
-
-Then, in the next chapters, you'll learn how to:
-
-- Link each product to a record of your data model.
-- Retrieve your data model's properties when you retrieve products.
-
----
-
 ## Set Delete Cascades on Link
 
 To enable delete cascade on a link so that when a record is deleted, its linked records are also deleted, pass the `deleteCascades` property in the object passed to `defineLink`.

www/apps/book/app/advanced-development/modules/container/page.mdx

@@ -8,11 +8,13 @@ In this chapter, you'll learn about the module's container and how to resolve re
 
 ## Module's Container
 
-Each module has a local container only used by the resources of that module.
+Since modules are isolated, each module has a local container only used by the resources of that module.
 
-So, resources in the module, such as services or loaders, can only resolve other resources registered in the module's container, such as:
+So, resources in the module, such as services or loaders, can only resolve other resources registered in the module's container.
 
-- `logger`: A utility to log message in the Medusa application's logs.
+### List of Registered Resources
+
+Find a list of resources or dependencies registered in a module's container in [this Learning Resources reference](!resoures!/medusa-container-resources).
 
 ---