Add projects folder documentation and layer-component mapping

AGENTS.md

@@ -37,6 +37,9 @@ uv run poly create component --name my_feature
 # Create a new base
 uv run poly create base --name my_api
 
+# Create a new project (deployable service)
+uv run poly create project --name my_service
+
 # View workspace info
 uv run poly info
 
@@ -63,6 +66,8 @@ polyclean/
 ├── bases/               # Entry points
 │   └── polyclean/
 │       └── publishing_api/
+├── projects/            # Deployable services
+│   └── publishing_service/
 └── test/                # Tests mirror component structure
     ├── flows/
     ├── adapters/
@@ -71,9 +76,19 @@ polyclean/
     └── fakes/
 ```
 
+**Projects** (in `projects/`) are deployable units - each has its own `pyproject.toml` defining which components/bases to include and service-specific dependencies.
+
 ## Architecture
 
-Clean Architecture layers:
+All Clean Architecture layers are implemented as Polylith components (bricks) in the `components/` folder:
+
+| Clean Architecture | Polylith Component | Naming Suffix |
+| ------------------ | ------------------ | ------------- |
+| Entities           | Contract           | `*_contract`  |
+| Ports              | Contract           | `*_contract`  |
+| Use Cases          | Flow               | `*_flow`      |
+| Adapters           | Adapter            | `*_adapter`   |
+| Layer Utilities    | Library            | `*_lib`       |
 
 - **Entities** - Domain objects (in `*_contract`)
 - **Use Cases** - Business logic (in `*_flow`)

PolyClean.md

@@ -203,10 +203,28 @@ PolyClean assumes a standard Python Polylith workspace.
 
 Top-level folders:
 
-- `bases/`
-- `components/`
-- `projects/`
-- `development/`
+- `bases/` - Application entry points (APIs, CLIs)
+- `components/` - Reusable building blocks (business logic, contracts, adapters)
+- `projects/` - Deployable units (service packaging)
+- `development/` - Scratchpad code for exploration
+
+### The Projects Folder
+
+The `projects/` folder contains **deployable units**. Each subdirectory is a separate Python package with its own `pyproject.toml` that defines:
+
+- Service-specific dependencies
+- Which components and bases to include
+- Build and packaging configuration
+
+Projects answer: **"What gets deployed?"**
+
+Components and bases answer: **"What code makes up the service?"**
+
+This separation allows:
+
+- Multiple services from shared code (e.g., REST API + background worker)
+- Independent deployment and versioning per service
+- Service-specific dependency lists
 
 Example `workspace.toml`:
 
@@ -239,7 +257,7 @@ theme = "loose"
 │       ├── sqlite_post_adapter/
 │       └── instagram_publish_adapter/
 ├── projects/
-│   └── publishing_service/
+│   └── publishing_service/      # Deployable service
 └── development/
     └── scratch.py
 ```

README.md

@@ -38,6 +38,8 @@ polyclean/
 ├── bases/               # Application entry points
 │   └── polyclean/
 │       └── publishing_api/
+├── projects/            # Deployable services
+│   └── publishing_service/
 └── test/                # Tests mirroring component structure
 ```