🎨 Palette: Improved onboarding and CLI delight

.Jules/palette.md

@@ -1,3 +1,7 @@
 ## 2025-05-15 - [Naming Conventions vs. Packaging Requirements]
 **Learning:** In projects using numbered prefixes for demo scripts (e.g., `01_script.py`), these files cannot be used directly as console script entry points in `pyproject.toml` because they are not valid Python module names. Attempting to "fix" this by renaming the files may break established naming conventions and user expectations.
 **Action:** Prefer maintaining existing naming conventions over forcing script entry points. If a demo script needs to be an entry point, create a separate wrapper module with a valid name rather than renaming the numbered file.
+
+## 2026-03-28 - [Guided CLI Onboarding]
+**Learning:** For tutorial-style scaffolds, adding "Next Step" guidance directly to the terminal output after a successful run creates a much smoother onboarding experience than relying solely on the README.
+**Action:** Always include a clear, visually distinct "Next Step" message at the end of introductory scripts to guide users through the intended learning path.

.github/workflows/python-ci.yml

@@ -0,0 +1,40 @@
+name: Python CI
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install . rich ruff black mypy
+
+      - name: Lint with Ruff
+        run: ruff check .
+
+      - name: Check formatting with Black
+        run: black --check .
+
+      - name: Type check with Mypy
+        run: mypy .
+
+      - name: Run demo scripts
+        run: |
+          python 01_getting_started.py
+          python 02_logging.py

01_getting_started.py

@@ -39,6 +39,11 @@ def main() -> list[str]:
             border_style="green",
         )
     )
+
+    console.print(
+        "\n[bold blue]➡️ Next Step:[/bold blue] Try running [cyan]python 02_logging.py[/cyan] to learn about logging in Prefect!"
+    )
+
     return results
 
 

02_logging.py

@@ -1,6 +1,10 @@
 from prefect import flow, task
 from prefect.logging import get_run_logger
 import random
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
 
 
 @task
@@ -35,7 +39,18 @@ def main() -> list[str]:
     # Map the process_customer task across all customer IDs
     results = process_customer.map(customer_ids)
 
-    print(f"✅ Successfully processed {len(results)} customers with detailed logging!")
+    console.print(
+        Panel.fit(
+            f"[bold green]✅ Successfully processed {len(results)} customers with detailed logging![/bold green]",
+            title="Success",
+            border_style="green",
+        )
+    )
+
+    console.print(
+        "\n[bold blue]🎉 You've completed the Quickstart! Check out the [cyan]README.md[/cyan] for more features.[/bold blue]"
+    )
+
     return results
 
 

README.md

@@ -12,37 +12,26 @@ At its core, QuickStart follows a simple philosophy: reduce noise, maximize clar
 
 Setup:
 
-git clone <your-repo-url>
-cd quickstart
-python -m venv .venv
-source .venv/bin/activate  (Windows: .venv\Scripts\activate)
-pip install -r requirements.txt
-quickstart run
+1. Clone the repository: `git clone <your-repo-url>`
+2. Create and activate a virtual environment: `python -m venv .venv && source .venv/bin/activate`
+3. Install dependencies: `pip install -e .`
+4. Run the first example: `python 01_getting_started.py`
 
 Project Structure:
 
-quickstart/
-├── quickstart/
-│   ├── __init__.py
-│   ├── core.py
-│   ├── flows.py
-│   ├── tasks.py
-│   └── cli.py
-├── tests/
-├── pyproject.toml
-├── requirements.txt
-├── requirements-dev.txt
-└── README.md
+.
+├── 01_getting_started.py  # Basic Prefect flow mapping
+├── 02_logging.py          # Prefect logging and stdout capture
+├── pyproject.toml         # Project metadata and dependencies
+└── README.md              # Project documentation
 
 Commands:
 
-quickstart run
-quickstart deploy
-quickstart test
+python 01_getting_started.py
+python 02_logging.py
 
 Development:
 
-pytest
 black .
 ruff check .
 mypy .
@@ -61,7 +50,7 @@ def pipeline():
 
 Run:
 
-python -m quickstart.flows
+python 01_getting_started.py
 
 Packaging:
 

pyproject.toml

@@ -7,5 +7,6 @@ requires-python = ">=3.10"
 dependencies = [
     "prefect",
     "prefect-cloud",
+    "rich",
 ]