docs: add info for library authors

docs/docs/05_considerations/03_for-library-authors.md

@@ -0,0 +1,17 @@
+# For library authors
+
+If you are developing a library that depends on `nestjs-cls`, please make sure of the following:
+
+## Use peer dependency
+
+List `nestjs-cls` as a peer dependency in your `package.json` (under `peerDependencies`), this prevents multiple instances of the library from being installed in the same project, which can lead to dependency injection errors and loss of context.
+
+## Do not import `forRoot`
+
+In your library, never import the module as `ClsModule.forRoot()` or `ClsModule.forRootAsync()`. This prevents the application from setting up the `nestjs-cls` library correctly.
+
+As with most other modules, importing a module `forRoot()` configures some global state, which can lead to unexpected behavior when used multiple times.
+
+If your library code needs to inject `ClsService`, it should be done by importing the `ClsModule` statically, without calling `forRoot()`.
+
+If you need to hook into the `setup` function to enrich the context, you can provide a custom function that the user must call manually, or provide a custom [Plugin](../06_plugins/index.md) and implement the `onClsInit` method, which is called right after `setup` in all enhancers.

docs/docs/06_plugins/02_plugin-api.md

@@ -4,7 +4,7 @@
 
 The Plugin API is still experimental and might change in the future, you should not rely on it in production.
 
-Using any of the "official" plugins is safe since they are maintained by the same author. If you want to create your own plugin, you should be aware that the API might change between minor versions.
+Using any of the "official" plugins is safe since they are maintained by the same author and compatibility of new versions is ensured. If you want to create your own plugin, you should be aware that the API might change between minor versions.
 
 :::
 
@@ -19,6 +19,7 @@ export interface ClsPlugin {
 
     /**
      * Function that is called within a Cls initializer (middleware, interceptor, guard, etc.)
+     * right after `setup`.
      */
     onClsInit?: (cls: ClsService) => void | Promise<void>;
 
@@ -28,7 +29,8 @@ export interface ClsPlugin {
     onModuleInit?: () => void | Promise<void>;
 
     /**
-     * A lifecycle method called when the `ClsModule` is destroyed (only when shutdown hooks are enabled)
+     * A lifecycle method called when the `ClsModule` is destroyed
+     * (only when shutdown hooks are enabled)
      */
     onModuleDestroy?: () => void | Promise<void>;
 
@@ -49,4 +51,4 @@ export interface ClsPlugin {
 }
 ```
 
-The plugin options are then mixed into a _global_ `ClsPluginModule` and the exposed providers can be used for injection by other plugin-related code.
+Each plugin creates a new instance of a _global_ `ClsPluginModule` and the exposed providers can be used for injection by other plugin-related code.