docs: rewrite the readme prose

The feature list sold the kit instead of describing it ("Production-ready",
"Seamless Security", "enterprise-ready", "Ship-ready"). Every bullet now
names what the thing actually does, so a reader can tell whether they want
it. The Project Structure section opened with four paragraphs of throat
clearing before the tree; it's two sentences now, and they say why a single
stack stops working rather than that modularity is good.

Fixes three things that were wrong rather than just wordy:

- Step 3 told you to `npm install -g aws-cdk`. The CDK CLI comes from the
  aws-cdk-cli PyPI package in the lockfile now, so `uv sync` covers it.
  Removing that step renumbered the rest, and step 6 pointed at the wrong
  one for account setup.
- `cdk bootstrap` in step 7 assumed a global install that no longer exists,
  so it's `uv run cdk bootstrap`.
- Step 7 ended in a stray double bracket.

Leaves the TIP-LIST block alone, since that's synced across repos.

Author: dannysteenman

README.md

@@ -2,20 +2,20 @@
 
 ## AWS CDK Python Starter Kit
 
-Production-ready AWS CDK Python starter kit template with secure OIDC authentication and automated CI/CD. Deploy infrastructure to AWS in minutes with projen-powered configuration.
+Deploy an AWS CDK app written in Python through GitHub Actions, without storing a single AWS credential. One projen config file generates the workflows, the tasks and the packaging.
 
 ### 🚀 Features
 
-- **⚡ Rapid Setup**: Jumpstart your project within minutes by tweaking a [single configuration file (projen)](./.projenrc.py)
-  - Preconfigured Python with uv dependency management via [pyproject.toml](./pyproject.toml)
-  - Pre-configured linting & formatting with [Ruff](https://github.com/astral-sh/ruff) for code quality
-  - Clean [project structure](#project-structure) for easy management of constructs and stacks
-- **🛡️ Seamless Security**: OIDC authentication for keyless AWS deployments - no stored credentials or long-lived secrets required, using GitHub's immutable repository subject claims
-- **🤖 Automated CI/CD**: Out-of-the-box GitHub Actions workflows with multi-account support for enterprise-ready deployments
-- **💬 Automated CDK Diff on PRs**: [CDK diff outputs](https://github.com/marketplace/actions/aws-cdk-diff-pr-commenter) are automatically posted to your pull requests for easy infrastructure change reviews
-- **💻 Branch-based Deployments**: Deploy multiple CDK stacks to the same AWS environments based on Git branch for an improved multi-developer workflow. Ephemeral environment deploys and destroys use CDK express mode, so they can run [up to 4x faster than normal deploys](https://aws.amazon.com/about-aws/whats-new/2026/06/aws-cloudformation-cdk/). Enable **"Automatically delete head branches"** in your repo settings so merged branch stacks are cleaned up automatically via the destroy workflow
-- **🧹 Reusable CDK Aspects**: Ship-ready [aspects](./src/aspects/README.md) that enforce permission boundaries, S3 encryption, public-access blocking and RFC 1918 VPC ranges across every stack
-- **📦 Reviewed Dependency Updates**: Dependabot opens grouped weekly upgrade PRs for uv. Nothing merges itself, and uv ignores any release younger than 7 days when resolving, so a compromised or broken publish has time to be caught and yanked before it can reach your lockfile
+- **⚡ One file to configure**: Set your accounts and region in [.projenrc.py](./.projenrc.py), run `uv run projen`, and the workflows, tasks and [pyproject.toml](./pyproject.toml) regenerate to match
+  - The CDK CLI is pinned in the lockfile alongside everything else, so your machine and CI run the same version
+  - [Ruff](https://github.com/astral-sh/ruff) for linting and formatting, [ty](https://github.com/astral-sh/ty) for type checking, both wired into the build
+  - A [project structure](#project-structure) that separates constructs, stacks and aspects instead of piling them into one file
+- **🛡️ Keyless deploys**: GitHub Actions assumes an IAM role through OIDC, so there's nothing in your repository secrets to leak. The trust policy pins GitHub's immutable subject claim, so renaming or recreating the repo can't hand its access to a different one
+- **🤖 Chained multi-account pipelines**: Push to `main` and `test` deploys. `production` runs only after `test` succeeds
+- **💬 CDK diff on every PR**: The [diff commenter](https://github.com/marketplace/actions/aws-cdk-diff-pr-commenter) posts what your change does to production before anyone approves it
+- **💻 Per-branch environments**: Push a feature branch and it gets its own stacks in the shared test account. Delete the branch and they go with it. Branch deploys use CDK express mode, [up to 4x faster](https://aws.amazon.com/about-aws/whats-new/2026/06/aws-cloudformation-cdk/) than a normal deploy
+- **🧹 Aspects you can switch on**: Four [aspects](./src/aspects/README.md) that catch an IAM role with no permission boundary, an unencrypted bucket, a bucket open to the public, and a VPC on public address space
+- **📦 Dependency updates that wait**: Dependabot opens grouped weekly PRs and nothing merges itself. uv skips any release younger than 7 days, so a bad publish has a week to get caught before it can reach your lockfile
 
 <!-- TIP-LIST:START -->
 > [!TIP]
@@ -63,19 +63,17 @@ Production-ready AWS CDK Python starter kit template with secure OIDC authentica
 
 ### Setup Guide
 
-All the config that is needed to personalise the CDK App to your environment is defined in the [.projenrc.py file](./.projenrc.py).
+Everything you need to change lives in [.projenrc.py](./.projenrc.py).
 
 **To get started, follow these steps:**
 
 1. Click the green ["Use this template"](https://github.com/new?template_name=aws-cdk-python-starter-kit&template_owner=towardsthecloud) button to create a new repository based on this starter kit.
 
 2. Add a Personal Access Token to the repository settings on GitHub, follow these [instructions for setting up a fine-grained personal access token](https://projen.io/docs/integrations/github/#fine-grained-personal-access-token-beta).
 
-3. Install the AWS CDK CLI: `npm install -g aws-cdk`
+3. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then run `uv sync`. That pulls in the pinned CDK CLI too, so you don't need a global `npm install -g aws-cdk`.
 
-4. Install uv (if needed) and sync dependencies: `uv sync`
-
-5. Customize the AWS Region and Account IDs in the [.projenrc.py](./.projenrc.py) file to match your AWS setup:
+4. Customize the AWS Region and Account IDs in the [.projenrc.py](./.projenrc.py) file to match your AWS setup:
 
 ```python
 # Define the AWS region for the CDK app and github workflows
@@ -96,39 +94,33 @@ environment_configs = [
 ]
 ```
 
-6. Run `uv run projen` to generate the github actions workflow files.
-
-7. AWS CLI Authentication: Ensure you're logged into an AWS Account (one of the ones you configured in step 4) via the AWS CLI. If you haven't set up the AWS CLI, [then follow this guide](https://towardsthecloud.com/set-up-aws-cli-aws-sso))
+5. Run `uv run projen` to generate the GitHub Actions workflow files.
 
-8. Deploy the CDK toolkit stack to your AWS environment with `cdk bootstrap` if it's not already set up.
+6. Log into one of the accounts you set in step 4 with the AWS CLI. If you haven't set that up yet, [follow this guide](https://towardsthecloud.com/set-up-aws-cli-aws-sso).
 
-9. Deploy the FoundationStack to create the GitHub Actions deploy role. For the `test` environment, run `uv run projen test:deploy:all`.
+7. Run `uv run cdk bootstrap` if the account doesn't have the CDK toolkit stack yet.
 
-   Local synth resolves your repository's numeric GitHub IDs through `gh api`, so run `gh auth login` first.
+8. Deploy the FoundationStack to create the GitHub Actions deploy role. For the `test` environment that's `uv run projen test:deploy:all`.
 
-10. Opt the repository into immutable OIDC subject claims:
+   Synthesizing locally reads your repository's numeric GitHub IDs through `gh api`, so run `gh auth login` first.
 
-    ```bash
-    gh api -X PUT repos/OWNER/REPOSITORY/actions/oidc/customization/sub -F use_default=true -F use_immutable_subject=true
-    ```
+9. Opt the repository into immutable OIDC subject claims:
 
-    The deploy role only trusts the immutable claim, so do this after step 9. See [`src/stacks/README.md`](./src/stacks/README.md#github-immutable-oidc-subjects).
+   ```bash
+   gh api -X PUT repos/OWNER/REPOSITORY/actions/oidc/customization/sub -F use_default=true -F use_immutable_subject=true
+   ```
 
-11. Commit and push your changes to the `main` branch to trigger the CDK deploy pipeline in GitHub.
+   The deploy role trusts only the immutable claim and there's no fallback to the old one, so do this after step 8, never before. [`src/stacks/README.md`](./src/stacks/README.md#github-immutable-oidc-subjects) explains why.
 
-Congratulations 🎉! You've successfully set up your project.
+10. Push to `main`. The pipeline takes it from there.
 
 ### Project Structure
 
-When working on smaller projects using infrastructure as code, where you deploy single applications that don’t demand extensive maintenance or collaboration from multiple teams, it’s recommended to structure your AWS CDK project in a way that enables you to deploy both the application and infrastructure using a single stack.
-
-However, as projects evolve to encompass multiple microservices and a variety of stateful resources (e.g., databases), the complexity inherently increases.
+One stack is fine while your app is a single service owned by one team. Put it all in `StarterStack` and move on.
 
-In such cases, adopting a more sophisticated AWS CDK project organization becomes critical. This ensures not only the ease of extensibility but also the smooth deployment of each component, thereby supporting a more robust development lifecycle and facilitating greater operational efficiency.
+That stops working once you have several services and stateful resources on different lifecycles, because every deploy then touches everything, including the database you'd rather nobody touched.
 
-To cater to these advanced needs, your AWS CDK project should adopt a modular structure. This is where the **AWS CDK Python Starter Kit** shines ✨.
-
-Here’s a closer look at how this structure enhances maintainability and scalability:
+So this kit splits the app along the seams that change independently:
 
 ```bash
 .
@@ -175,17 +167,15 @@ Here’s a closer look at how this structure enhances maintainability and scalab
    └── test_git_helper.py
 ```
 
-As you can see in the above tree diagram, the way this project is setup it tries to segment it into logical units, such as **constructs** for reusable infrastructure patterns, **stacks** for deploying groups of resources and **assets** for managing source code of containers and lambda functions.
-
-Here is a brief explanation of what each section does:
+Each directory has one job:
 
-- `src/aspects`: Rules applied across every construct in a scope, such as attaching a permission boundary to every IAM role. Check out the [README in the aspects folder](./src/aspects/README.md) for what each one does and how to write your own.
-- `src/assets`: Organizes the assets for your Lambda functions and ECS services, ensuring that the application code is neatly encapsulated with the infrastructure code.
-- `src/bin`: Contains utility scripts (e.g., `cicd_helper.py`, `env_helper.py`, `git_helper.py`) that streamline environment setup and integration with CI/CD pipelines.
-- `src/custom_constructs`: Houses the core building blocks of your infrastructure. These constructs can be composed into higher-level abstractions, promoting reusability across different parts of your infrastructure. Check out the [README in the constructs folder](./src/custom_constructs/README.md) to read how you can utilize environment-aware configurations. The folder is named `custom_constructs` rather than `constructs` because that name would shadow the `constructs` package every CDK module imports.
-- `src/stacks`: Dedicated to defining stacks that represent collections of AWS resources (constructs). This allows for logical grouping of related resources, making it simpler to manage deployments and resource dependencies. Check out the [README in the stacks folder](./src/stacks/README.md) to read how you can instantiate new stacks.
-- `src/app.py`: This is where the CDK app is instantiated.
-- `tests`: Is the location to store your unit or integration tests (powered by pytest)
+- `src/aspects`: Rules applied to every construct in a scope, like attaching a permission boundary to each IAM role. The [aspects README](./src/aspects/README.md) covers what each one catches and how to write your own.
+- `src/assets`: Lambda handler code and container Dockerfiles, sitting next to the infrastructure that ships them.
+- `src/bin`: Helpers shared by the CDK app and `.projenrc.py`: resource naming, workflow generation, and resolving this repository's GitHub identity.
+- `src/custom_constructs`: Reusable building blocks you compose into stacks. The [constructs README](./src/custom_constructs/README.md) covers the environment-aware pattern. It's called `custom_constructs` because a directory named `constructs` would shadow the `constructs` package every CDK module imports.
+- `src/stacks`: `FoundationStack` holds the account-level pieces (the deploy role and the toolkit cleaner), and `StarterStack` is where your own resources go. See the [stacks README](./src/stacks/README.md).
+- `src/app.py`: Where the app gets built and the stacks get their names.
+- `tests`: pytest tests. `uv run projen test` runs them together with Ruff and ty.
 
 ### Branch-based Deployments
 
@@ -211,11 +201,11 @@ uv run projen test:ls
 
 ### AWS CDK Starter Kit for TypeScript Users
 
-> **Looking for the TypeScript version of this AWS CDK Starter Kit?** Check out the [AWS CDK Starter Kit](https://github.com/towardsthecloud/aws-cdk-starter-kit) for a tailored experience that leverages the full power of AWS CDK with TypeScript.
+> Prefer TypeScript? The [AWS CDK Starter Kit](https://github.com/towardsthecloud/aws-cdk-starter-kit) is the same setup, written in TypeScript.
 
 ### Acknowledgements
 
-A heartfelt thank you to the creators of [projen](https://github.com/projen/projen). This starter kit stands on the shoulders of giants, made possible by their pioneering work in simplifying cloud infrastructure projects!
+Thanks to the [projen](https://github.com/projen/projen) team. Every workflow, task and config file in this repo is generated, and none of it would exist without their work.
 
 ### Author