From 20554411b375688a4bfe4a41a8da98005144d616 Mon Sep 17 00:00:00 2001 From: ulises-jeremias Date: Thu, 16 Jul 2026 03:19:43 -0300 Subject: [PATCH] docs: BRAND, DISTRIBUTION_SETUP, TROUBLESHOOTING, MIGRATION, ADR Closes #56 Co-authored-by: Cursor --- docs/BRAND.md | 6 ++++++ docs/DISTRIBUTION_SETUP.md | 10 ++++++++++ docs/MIGRATION.md | 7 +++++++ docs/TROUBLESHOOTING.md | 5 +++++ docs/UIUX_BRANDING_HANDOFF.md | 3 +++ docs/adr/0001-uv-workspaces.md | 9 +++++++++ 6 files changed, 40 insertions(+) create mode 100644 docs/BRAND.md create mode 100644 docs/DISTRIBUTION_SETUP.md create mode 100644 docs/MIGRATION.md create mode 100644 docs/TROUBLESHOOTING.md create mode 100644 docs/UIUX_BRANDING_HANDOFF.md create mode 100644 docs/adr/0001-uv-workspaces.md diff --git a/docs/BRAND.md b/docs/BRAND.md new file mode 100644 index 0000000..e4a85c0 --- /dev/null +++ b/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 diff --git a/docs/DISTRIBUTION_SETUP.md b/docs/DISTRIBUTION_SETUP.md new file mode 100644 index 0000000..7bcdfe3 --- /dev/null +++ b/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` | diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md new file mode 100644 index 0000000..018e370 --- /dev/null +++ b/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 diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..d1e88e0 --- /dev/null +++ b/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 diff --git a/docs/UIUX_BRANDING_HANDOFF.md b/docs/UIUX_BRANDING_HANDOFF.md new file mode 100644 index 0000000..5b75cf3 --- /dev/null +++ b/docs/UIUX_BRANDING_HANDOFF.md @@ -0,0 +1,3 @@ +# UI/UX branding handoff + +Placeholder for website/marketing assets once the docs site exists. diff --git a/docs/adr/0001-uv-workspaces.md b/docs/adr/0001-uv-workspaces.md new file mode 100644 index 0000000..4be94c2 --- /dev/null +++ b/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`.