# caddie — 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:** The client-facing project hub at `caddie.bowden.works` (port 3143).
A client signs in and sees THEIR project: where it stands, what's needed from
them, and reference details. The agency composes each project from linear
stages; anything interactive is a sovereign standalone **tool** app on its own
subdomain, integrated through the Caddie Tool Contract.
**Why:** Keep clients in the loop without chasing them, and give rian's
growing library of client-facing tools (punchlist, scout, review, …) one
signed-in journey to live in. A future caddie rebuild is expected — so the
durable artifact is the contract and the tools, and the hub stays deliberately
thin and boring.
**Who:** rian (agency) + invited external client BW accounts, granted
per-project.
**Status:** M1 complete (0.3.1: the gate runs as a test). 0.4.0 (2026-09-02)
aligned caddie to the standards it publishes: the shared `caddie-ui` pack is
canonical here and caddie wears it (two-row shell, the one side-panel
Discussion, the pack's bell); the conversation layer carries all of 04 §3–4.
Next: the gate with a real client on a phone, then M2 (the contract made
real).

## Where everything is
| Role | Lives in |
|---|---|
| Vision, domain model, decisions, roadmap | `.logs/planning/01-vision-and-roadmap.md` |
| The Caddie Tool Contract (ct1) | `.logs/planning/02-tool-contract.md` |
| The BW Interaction Standard | `.logs/planning/04-interaction-standard.md` |
| Building a caddie app (the runbook) | `.logs/planning/05-building-a-caddie-app.md` |
| The shared UI pack — canonical copy + stamp/check tooling | `packs/caddie-ui/`, `packs/stamp-caddie-ui.sh` |
| Coordination with the tool sessions | `.logs/planning/06-punchlist-coordination.md`, `07-easel-coordination.md` |
| Session handoff (what next) | `.logs/handoff.md` |
| Project constitution | `agents.md` |

## Stack
React SPA + FastAPI, one Python process (the BW-app scaffold), plus a
**Postgres sidecar from day one** — caddie has real domain tables (stages,
assignments, activity), and the auth kit's store moves into the same Postgres
via `bw_store_sqlalchemy.managed(...)` (PACKS.md managed mode; scout is
kit-on-Postgres precedent but uses a pre-module custom store — don't copy its
adapter). SQLAlchemy 2.0 + Alembic. Standards dispatch: `coding.md` → `react.md` → `frontend.md`.

A caddie **project** is a kit instance (`instance_noun = "project"`); clients
are external BW accounts invited + granted per-project. Caddie is NOT a client
registry — `with` is the system-of-record; caddie stores `client_party_id`
(party = person OR organization), keeps the client name only as a refreshable
hint, and stores no role.

**A caddie app implements two shared standards**: the Tool Contract (launch +
status) and the Interaction Standard (comments, @mentions, attachments, one
cross-app notification bell). Caddie itself is just another consumer of both.

## Not doing
- **No workflow engine in caddie** — stages are concurrent, human-advanced
  workstreams, not a state machine. Any interactive need is a tool, and the
  tools (never caddie) decide whose turn it is.
- **No tool code inside caddie** — tools are standalone apps; integration is
  the contract only.
- No client/org registry, no notifications engine (seam recorded, substrate
  ask pending), no recurring stages (v2), no embed mode until a tool earns it.

## Known gaps
- The contract's drop-ins (`caddie_tool.py`, `caddieHost.ts`) and the
  `bw_interaction` extraction are not built — M2.
- No notification substrate exists server-wide; until the central notify
  endpoint is approved, the BW invite email is the only outbound touch.
- The silent-SSO handoff and the new-client bootstrap chain are designed but
  unmeasured — both have named tests in the roadmap (risks R1/R2).