docs: Poetry plugin docs and clarifications

README.md

@@ -27,7 +27,7 @@ there is a `interface.clj` file that is used to separate an API from the impleme
 The Python implementation uses the `__init__.py` to accomplish that. In the Python implementation, the `pyproject.toml` is used to define bases and components.
 In particular, the `packages` property is used for that.
 
-This is an example of the top level `pyproject.toml` used during __development__.
+This is an example of the _top level_ `pyproject.toml` used when _developing_. This is where you add all bricks (components and bases).
 
 ``` shell
  packages = [
@@ -41,6 +41,8 @@ This is an example of the top level `pyproject.toml` used during __development__
 When creating a project, the project specific `pyproject.toml` will include all the used components and bases.
 Note that the packages are referenced relative to the project.
 
+This is where you add the bricks used by the actual project.
+
 ``` shell
  packages = [
     {include = "my_namespace/my_component", from = "../../components"},

projects/poetry_polylith_plugin/README.md

@@ -1,8 +1,51 @@
-# poetry-polylith-plugin
+# Poetry Polylith Plugin
 
-This is a Python `Poetry` plugin, adding CLI support for the Polylith architecture.
+This is a Python `Poetry` plugin, adding CLI support for the Polylith Architecture.
 
 
+## What's Polylith?
+From the [official docs](https://polylith.gitbook.io/polylith/):
+
+>... Polylith is a software architecture that applies functional thinking at the system scale. It helps us build simple, maintainable, testable, and scalable backend systems. ...
+
+Polylith is an architecture (with tooling support) originally built for Clojure.
+With this Poetry plugin, Polylith is available in Python too!
+
+### An Architecture well suited for Monorepos
+Polylith is using a components-first architecture. Similar to LEGO, components are building blocks.
+A component can be shared across apps, tools, libraries, serverless functions and services.
+
+
+### Differences between the Clojure & Python implementations
+In the [official docs](https://polylith.gitbook.io/polylith/) for the Clojure implementation,
+there is a `interface.clj` file that is used to separate an API from the implementation of a component.
+
+The Python implementation uses the `__init__.py` to accomplish that. In the Python implementation, the `pyproject.toml` is used to define bases and components.
+In particular, the `packages` property is used for that.
+
+This is an example of the _top level_ `pyproject.toml` used when _developing_. This is where you add all bricks (components and bases).
+
+``` shell
+ packages = [
+    {include = "development"},
+    {include = "my_namespace/my_component", from = "components"},
+    {include = "my_namespace/my_example_aws_lambda", from = "bases"},
+]
+```
+(using the `loose` theme, see more about that below)
+
+When creating a project, the _project specific_ `pyproject.toml` will include all the used components and bases.
+Note that the packages are referenced relative to the project. This is made possible by the Multiproject Poetry plugin.
+
+This is where you add the bricks used by the actual project.
+
+``` shell
+ packages = [
+    {include = "my_namespace/my_component", from = "../../components"},
+    {include = "my_namespace/my_example_aws_lambda", from = "../../bases"},
+]
+```
+
 ## Usage
 
 ### Install Poetry & plugins