docs: BRAND, DISTRIBUTION_SETUP, TROUBLESHOOTING, MIGRATION, ADR

Closes #56

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

Author: ulises-jeremias

docs/BRAND.md

@@ -0,0 +1,6 @@
+# Brand
+
+Working identity for CPA (to be refined):
+
+- Tagline: One command. Any Python stack.
+- Story: choose template → add addons → ship with uv

docs/DISTRIBUTION_SETUP.md

@@ -0,0 +1,10 @@
+# Distribution Setup
+
+Secrets and publishers (see also #58–#63):
+
+| Channel | Secret / config |
+|---------|-----------------|
+| PyPI | Trusted Publishing OIDC (no long-lived token) |
+| Docker Hub | `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN` |
+| AUR | `AUR_SSH_PRIVATE_KEY`, `AUR_REPO_TOKEN` |
+| Homebrew | `HOMEBREW_TAP_TOKEN` |

docs/MIGRATION.md

@@ -0,0 +1,7 @@
+# Migration
+
+From hand-rolled Cookiecutter/Copier flows:
+
+1. Map template repo to `templates.json` entry
+2. Add `cpa.config.json`
+3. Prefer `uv` lockfiles in generated projects

docs/TROUBLESHOOTING.md

@@ -0,0 +1,5 @@
+# Troubleshooting
+
+- `uv sync` fails: check `.python-version` and network
+- Non-empty target dir: pass `--force`
+- Offline scaffold: ensure cache warmed or use `file://` fixtures

docs/UIUX_BRANDING_HANDOFF.md

@@ -0,0 +1,3 @@
+# UI/UX branding handoff
+
+Placeholder for website/marketing assets once the docs site exists.

docs/adr/0001-uv-workspaces.md

@@ -0,0 +1,9 @@
+# ADR 0001: uv virtual workspace monorepo
+
+## Decision
+
+Use a virtual uv workspace root (`packages/*`, single `uv.lock`) instead of Poetry/PDM.
+
+## Consequences
+
+Shared `.venv`, consistent dependency resolution, fast CI via `astral-sh/setup-uv`.