fix: lambda as package + docs

Author: pepe5p

skeleton/README.md.jinja

@@ -36,14 +36,47 @@ just lint_full_ff  # (fast-fail mode)
 just all  # (lint + tests)
 just all_ff  # (lint + tests in fast-fail mode)
 ```
-
 {%- if is_lambda_project %}
-## Deployment to AWS Lambda
-1. Package the application:
-    ```bash
-    just build
-    ```
 
-2. You will see in `/build` directory a zip file ready for deployment to AWS Lambda.
-{%- endif %}
+## Building and Deployment
+
+### Building the Lambda Package
+
+The project includes a build system that packages the application for AWS Lambda deployment:
+
+```bash
+just build
+```
+
+This command:
+1. Clears the previous build directory (`build/pkg`)
+2. Generates a frozen requirements file without dev dependencies
+3. Installs all dependencies targeting `x86_64-manylinux2014` platform (compatible with AWS Lambda)
+4. Copies the lambda handler shim (`lambda_function.py`) to the package
+5. Creates a timestamped zip file in the `build/` directory (e.g., `{{ project_name_snake_case }}_20260201_005935.zip`)
 
+The resulting zip file contains:
+- All Python dependencies
+- The `{{ source_catalog_name }}` package with your application code
+- A `lambda_function.py` shim that exposes the handler
+
+### Lambda Handler Shim
+
+The project uses a shim file (`lambda_function.py`) at the root level to expose the Lambda handler:
+
+This allows AWS Lambda to use the default handler configuration `lambda_function.lambda_handler` while keeping the actual implementation inside the `{{ source_catalog_name }}` package.
+
+**Package Structure:**
+```
+build/pkg/
+├── lambda_function.py          # Shim that exposes the handler
+├── {{ source_catalog_name }}/
+│   ├── __init__.py
+│   ├── lambda_function.py      # Actual handler implementation
+│   └── ...
+├── aws_lambda_powertools/
+└── ... (other dependencies)
+```
+
+**Note:** The shim file can be safely deleted if you update the AWS Lambda **Runtime settings** → **Handler** configuration to point directly to `{{ project_name_snake_case }}.lambda_function.lambda_handler`.
+{%- endif %}

skeleton/justfile.jinja

@@ -109,7 +109,7 @@ dc command *args:
 [group("lambda_build")]
 build: build_create_env
 	cd {{ BUILD_DIR }}/pkg && \
-	zip -r ../{% endraw %}{{ source_catalog_name }}{% raw %}_{{ CURRENT_DATETIME }}.zip .
+	zip -r ../{% endraw %}{{ project_name_snake_case }}{% raw %}_{{ CURRENT_DATETIME }}.zip .
 
 [group("lambda_build")]
 build_create_env: clear_build_dir build_generate_requirements build_install copy_shim

skeleton/pyproject.toml.jinja

@@ -28,15 +28,16 @@ dev = [
     "python-dotenv>=1.2.1,<2",
     {%- endif %}
 ]
-
 {%- if is_lambda_project %}
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
-{%- endif %}
+{%- else %}
 
 [tool.uv]
 package = false
+{%- endif %}
 
 [tool.ruff]
 line-length = 120