Learning Path

Follow these steps in order. Each link is self-contained; later steps assume earlier ones.

1. Install and verify

Installation —pip install bengal-chirp or uv add bengal-chirp, Python 3.14+.

For new projects, add the UI extra sochirp newscaffolds ChirpUI layouts:

pip install 'bengal-chirp[ui]'

2. Run your first app

Pick one entry point:

• Scaffold (recommended): Quickstart —chirp new myapp && python app.py
• Smallest loop: First Fragment App — one file, one template,Page / Fragment, tests

Both teach the hypermedia loop: full page for browsers, HTML fragment for htmx.

3. Learn the mental model

Return values — the type is the intent (Template, Page, Fragment, FormAction, …).

Skim Hypermedia model if you want the why before building more.

4. Learn project shape

Project layout — wherechirp newputs handlers, templates, static files, and tests.

5. Tier 1 — basics (examples)

Run and read the standalone examples:

Recipe collection: htmx Patterns.

6. Validate wiring

Contracts — whatchirp checkvalidates and why.

Run on your app:

chirp check myapp:app
chirp check myapp:app --warnings-as-errors   # CI posture

Category reference: Contract categories.

7. Tier 2 — app shell (optional)

When you want ChirpUI layouts and boosted navigation:

Contacts shell —_actions.py, _context.py, shell swaps.

8. Tier 3 — capstone

Lucky Cat — signals, Suspense, SSE, OOB, auth, secure stack.

Live demo: luckycat-production.up.railway.app · Source:examples/chirpui/lucky_cat/

Complete tiers 1–2 first. Lucky Cat is the composed product demo, not the on-ramp.

9. Ship

When you deploy:

Production deployment — Pounce,chirp check --deploy, workers, metrics.

Where to go after this path