# punchlist — brief

<!-- The genesis document: what this is, why it exists, who it's for, and what
     "done" looks like. Write-once-read-always. Keep it thin — it is always
     loaded. Detailed how-it-works goes in .logs/planning/ or docs. -->

**What:** A to-do list with a twist, at `punchlist.bowden.works` (port 3145).
Clients work items that look like a dead-simple checklist; underneath each item
runs a workflow (owners, context-aware actions, alternatives, per-target
checks, tutorials). Four personas: clients / team (confirm+respond) / managers
(compose) / builders (author workflows — AI-first).
**Why:** Getting clients to DO things (grant Google access, send IDs) without
chasing them. First caddie tool — also the build that teaches caddie what a
"caddie app" needs (learnings flow to caddie's planning/05 runbook).
**Who:** rian + agency team (app-wide levels) + invited external client BW
accounts granted per-punchlist.
**Status:** Scaffolded 2026-08-20; building M1 (engine + seeds + client/team
views). Plan: `.logs/planning/01-plan.md`.

## Where everything is
| Role | Lives in |
|---|---|
| Build plan, milestones, gates | `.logs/planning/` |
| Session handoff (what next) | `.logs/handoff.md` |
| Project constitution | `agents.md` |
| Human reference material | `notes/` |

## Stack
React SPA + FastAPI (BW-app scaffold), one Python process; **Postgres sidecar
from day one** with the auth kit's store in `bw_store_sqlalchemy` managed mode
(PACKS.md); SQLAlchemy 2.0 + Alembic; event-sourced runtime (append-only
`item_events`). Kit instance noun: **punchlist**. Standards dispatch:
`coding.md` → `react.md` → `frontend.md`; caddie-app requirements:
`/srv/apps/caddie/.logs/planning/05-building-a-caddie-app.md`.

## Not doing
Parallel steps · due dates · builder UI before the AI/API authoring path ·
outbound delivery (bell arrives with the interaction kit in M2) · any client
registry (`client_party_id` only) · template upgrade-in-place · embed mode.

## Known gaps
- The caddie drop-ins (`caddie_tool.py`, `caddieHost.ts`) don't exist yet
  (caddie M2); M1-M2 build the seams only.
- The interaction kit doesn't exist yet; M1 ships a message-on-event embryo,
  M2 swaps in the real kit (extracted from this build).