docs: overhaul CPA package README to CNA parity

Rewrite the PyPI-facing create-awesome-python-app README with install
channels, recipes, CLI/cache reference, and site links; refresh the
monorepo README to point users at the package docs (#221).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ulises-jeremias

README.md

@@ -1,4 +1,12 @@
-# create-python-app
+<!--lint disable double-link awesome-heading awesome-git-repo-age awesome-toc-->
+
+<div align="center">
+
+# Create Awesome Python App
+
+**The open-source monorepo behind `create-awesome-python-app`: compose templates and addons into production-ready Python, FastAPI, Django, Celery, CLI, and uv workspace projects.**
+
+One command. Any stack.
 
 [![CI Tests](https://github.com/Create-Python-App/create-python-app/actions/workflows/test.yml/badge.svg)](https://github.com/Create-Python-App/create-python-app/actions/workflows/test.yml)
 [![Lint](https://github.com/Create-Python-App/create-python-app/actions/workflows/lint.yml/badge.svg)](https://github.com/Create-Python-App/create-python-app/actions/workflows/lint.yml)
@@ -9,70 +17,70 @@
 [![Homebrew](https://img.shields.io/badge/homebrew-Create--Python--App%2Ftap-orange?logo=homebrew)](https://github.com/Create-Python-App/homebrew-tap)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-Composable scaffolding CLI for production-ready Python apps.
+[Package README](./packages/create-awesome-python-app/README.md) · [Official Site](https://create-awesome-python-app.vercel.app) · [Templates](https://create-awesome-python-app.vercel.app/templates) · [Extensions](https://create-awesome-python-app.vercel.app/extensions) · [Contributing](./CONTRIBUTING.md) · [Troubleshooting](./docs/TROUBLESHOOTING.md)
 
-> **Status:** CLI monorepo bootstrapped. Template bank: [`cpa-templates`](https://github.com/Create-Python-App/cpa-templates). Roadmap: [#1](https://github.com/Create-Python-App/create-python-app/issues/1).
+</div>
 
-## Ecosystem
+---
 
-| Repository | Role |
-|------------|------|
-| [create-python-app](https://github.com/Create-Python-App/create-python-app) (this repo) | CLI (`create-awesome-python-app`) and scaffolding engine (`create-python-app-core`) |
-| [cpa-templates](https://github.com/Create-Python-App/cpa-templates) | Official templates and extensions (`templates.json` catalog) |
-| [homebrew-tap](https://github.com/Create-Python-App/homebrew-tap) | Homebrew formula |
-| [aur-package](https://github.com/Create-Python-App/aur-package) | AUR PKGBUILD mirror |
+## What This Repo Contains
 
-The CLI fetches the catalog from:
+This repository contains the source code for [`create-awesome-python-app`](https://pypi.org/project/create-awesome-python-app/), the CLI that composes curated templates, addons, custom options, and AI-ready conventions into working projects.
 
-`https://raw.githubusercontent.com/Create-Python-App/cpa-templates/main/templates.json`
+Use this README if you want to understand the codebase, run it locally, contribute a fix, improve documentation, or work on the CLI packages. If you only want to generate an app, start with the [package README](./packages/create-awesome-python-app/README.md).
 
-Override with `CPA_CATALOG_URL` for forks or local testing (`file://` supported).
+---
 
-## Install
+## Quick Start For Users
 
 ```bash
-# PyPI / uv
 uvx create-awesome-python-app@latest my-app
-
-# Homebrew
-brew tap Create-Python-App/tap
-brew install create-awesome-python-app
-
-# AUR
-yay -S create-awesome-python-app
-
-# Docker
-docker run --rm -it -v "${PWD}:/app" -w /app \
-  ulisesjeremias/create-awesome-python-app my-app
 ```
 
-Or pin a version:
+Run headlessly for scripts, CI, or platform automation:
 
 ```bash
-uvx create-awesome-python-app@0.1.0 my-app --template fastapi-starter --no-interactive
+uvx create-awesome-python-app my-api \
+  --template fastapi-starter \
+  --addons github-setup \
+  --addons fastapi-sqlalchemy \
+  --no-interactive
 ```
 
-From this workspace (development):
+More examples live in the [CLI package README](./packages/create-awesome-python-app/README.md).
 
-```bash
-uv sync
-uv run create-awesome-python-app --help
-```
+---
 
-### Shell completion
+## Ecosystem
 
-```bash
-create-awesome-python-app --install-completion   # bash / zsh / fish
-create-awesome-python-app --show-completion      # print script only
-```
+| Repository | Role |
+|------------|------|
+| [create-python-app](https://github.com/Create-Python-App/create-python-app) (this repo) | CLI (`create-awesome-python-app`) and scaffolding engine (`create-python-app-core`) |
+| [cpa-templates](https://github.com/Create-Python-App/cpa-templates) | Official templates and extensions (`templates.json` catalog) |
+| [website](https://github.com/Create-Python-App/website) | Docs + catalog UI ([create-awesome-python-app.vercel.app](https://create-awesome-python-app.vercel.app)) |
+| [homebrew-tap](https://github.com/Create-Python-App/homebrew-tap) | Homebrew formula |
+| [aur-package](https://github.com/Create-Python-App/aur-package) | AUR PKGBUILD mirror |
 
-## License
+The CLI fetches the catalog from:
 
-MIT — see [LICENSE](./LICENSE).
+`https://raw.githubusercontent.com/Create-Python-App/cpa-templates/main/templates.json`
+
+Override with `CPA_CATALOG_URL` for forks or local testing (`file://` supported).
 
-## Monorepo layout (uv workspaces)
+---
 
-This repository is a **virtual uv workspace**: the root is not published; packages live under `packages/*` and share one `uv.lock` / `.venv`.
+## Repository Map
+
+This is a **virtual uv workspace**: the root is not published; packages live under `packages/*` and share one `uv.lock` / `.venv`.
+
+| Path | Purpose |
+|------|---------|
+| [`packages/create-awesome-python-app`](./packages/create-awesome-python-app) | Main CLI package (Typer), interactive wizard, catalog listing |
+| [`packages/create-python-app-core`](./packages/create-python-app-core) | Scaffolding engine: resolve sources, merge layers, install, git init |
+| [`docs/`](./docs) | Brand, troubleshooting, migration, distribution, versioning |
+| [`.github/workflows`](./.github/workflows) | CI, release, Docker / Homebrew / AUR publish, distribution smoke |
+
+Template and extension data is maintained in [`Create-Python-App/cpa-templates`](https://github.com/Create-Python-App/cpa-templates). This repo consumes that catalog remotely.
 
 ```text
 create-python-app/          # virtual workspace root (no [project] table)
@@ -84,16 +92,34 @@ create-python-app/          # virtual workspace root (no [project] table)
     └── create-awesome-python-app/    # CLI (depends on core via workspace)
 ```
 
-### Setup
+---
+
+## Local Development
+
+Requires **Python 3.12+** (pinned in `.python-version`) and [uv](https://docs.astral.sh/uv/):
 
 ```bash
-# Requires uv: https://docs.astral.sh/uv/
+git clone https://github.com/Create-Python-App/create-python-app.git
+cd create-python-app
 uv sync --group dev
+uv run create-awesome-python-app --help
 ```
 
-## Development commands
+Non-interactive local smoke test:
 
-From the repo root (requires [uv](https://docs.astral.sh/uv/)):
+```bash
+uv run create-awesome-python-app smoke-app \
+  --template fastapi-starter \
+  --addons github-setup \
+  --no-interactive \
+  --no-install
+```
+
+Install git hooks: `uv run pre-commit install`
+
+---
+
+## Development Commands
 
 | Task | Make | Equivalent |
 |------|------|------------|
@@ -103,38 +129,45 @@ From the repo root (requires [uv](https://docs.astral.sh/uv/)):
 | Type-check | `make typecheck` | `uv run pyright` |
 | Build packages | `make build` | `uv build --all` |
 
-Install git hooks: `uv run pre-commit install`
-
-## Python version
+---
 
-- **Pin file:** `.python-version` → `3.12`
-- **Constraint:** every workspace member sets `requires-python = ">=3.12"`
-- **CI:** workflows install Python 3.12+ matching this pin
+## Install Channels (published package)
 
 ```bash
-uv python install
-uv sync --group dev
-```
+# PyPI / uv
+uvx create-awesome-python-app@latest my-app
 
-## Docker
+# Homebrew
+brew tap Create-Python-App/tap
+brew install create-awesome-python-app
 
-Published image: [`ulisesjeremias/create-awesome-python-app`](https://hub.docker.com/r/ulisesjeremias/create-awesome-python-app)
+# AUR
+yay -S create-awesome-python-app
 
-```bash
-docker run --rm ulisesjeremias/create-awesome-python-app:0.1.0 --version
+# Docker
 docker run --rm -it -v "${PWD}:/app" -w /app \
-  ulisesjeremias/create-awesome-python-app my-app --template fastapi-starter --no-interactive
+  ulisesjeremias/create-awesome-python-app:latest my-app \
+  --template fastapi-starter
 ```
 
-Local build (installs the given PyPI version into the image):
+Published image: [`ulisesjeremias/create-awesome-python-app`](https://hub.docker.com/r/ulisesjeremias/create-awesome-python-app)
+
+Local image build (installs the given PyPI version into the image):
 
 ```bash
-docker build --build-arg VERSION=0.1.0 -t create-awesome-python-app .
+docker build --build-arg VERSION=0.2.5 -t create-awesome-python-app .
 docker run --rm create-awesome-python-app --help
 ```
 
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
 ### Reference
 
+- [Package README](./packages/create-awesome-python-app/README.md) — user-facing CLI docs
 - [uv workspaces handbook](https://pydevtools.com/handbook/how-to/how-to-set-up-a-python-monorepo-with-uv-workspaces/)
 - [cpa-templates](https://github.com/Create-Python-App/cpa-templates) — template and extension bank
 - Node parity: [Create-Node-App/create-node-app](https://github.com/Create-Node-App/create-node-app) + [cna-templates](https://github.com/Create-Node-App/cna-templates)